top_n 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cda9c5805aaeda70a3ea35e8a01314a96e071cd5
-  data.tar.gz: f581488f6929408afe40e98567b076fc1d09f42f
+  metadata.gz: 803c6da6c638a4f7c2ae8ac20eb92d1e39703df9
+  data.tar.gz: 57b04413328c9c6c114603a752a188f99abb648e
 SHA512:
-  metadata.gz: f55b87b0711b17b8fee03294baffa347c1df8fb92f010198418870ed5a337a2559358e76cd4a92ded26c424da9e9a9abfea7ef9bea9c744723a3cd3a62b8d2b4
-  data.tar.gz: dab46fa2befd85a4edc51c5c7bef1f4f41b43e1e57ee2aaae0ff5031cf1a0e6fb458f58261e6ca7b20dd5de288edd6bf625d57acc5f0bc942d5a06249f6e19e3
+  metadata.gz: 4cf9a41e670df85e675638d9fa6078889113bcd7dfc957287b5082522969251ae6f2c36489b1650c23856846a551fb50ccc2a5b3035a7af47787404e4bc56d50
+  data.tar.gz: 0f4bd0478afba479f1a10a443b4786f9b0d32f7599efe7cbdd356557502c5a00987c7fc38e8c7af7cf7035653d714a58219f80b9000b3b13cdd01eb7b92eeb4e

data/README.rdoc

@@ -3,7 +3,7 @@
 {<img src="https://travis-ci.org/skandragon/top_n.png?branch=master" alt="Build Status" />}[https://travis-ci.org/skandragon/top_n]
 
 This gem allows tracking of the top N (or bottom N) keys added to a list.
-Each key can have an optional value, which is then added to a list of values for that key.
+Each key can have an optional value, which is then added to a list of values for that key.  It acts a lot like a norman Ruby Hash type, but with a limited number of keys based on sorting order.
 
 Key types must respond to the usual comparison operators: <, <=, >, >=, and <=>.  Values may be any object type, and need not be unique.  Values are not examined in any way, simply added to an internal list.
 

data/VERSION

@@ -1 +1 @@
-1.0.1
+1.1.0

data/lib/top_n.rb

@@ -14,36 +14,29 @@
 #   This can cause memory issues if many values are added to the same key.
 #   If this is the type of data you are tracking, you may need a different
 #   solution.
-class TopN
+class TopN < Hash
   # The maxinum number of keys which will be tracked.
   # @return [Fixnum] the configured maximum number of keys to be tracked.
-  attr_reader :maxsize
+  attr_reader :maxkeys
 
   # The configured direction.
   # @return [Symbol] either :top or :bottom.
   attr_reader :direction
 
-  # The current number of keys we are tracking.
-  # @return [FixNum] the count, which will be 0 up to :maxsize.
-  attr_reader :size
-
   # The current value of the minimum (:top) or maximum (:bottom) key.
   # @return [Object] the threshold key.
   attr_reader :threshold_key
 
-  # The currently tracked data as one blob.  This is tied to the
-  # current implementation, so its use is not recommended.
-  # @return [Hash] the internal data structure containing the keys and
-  #  values.  The keys to the returned Hash are the tracked keys, and
-  #  the values at those keys is the list of values.
-  attr_reader :data
+  alias_method :super_store, :store
+  alias_method :super_bracket_assign, :[]=
+  alias_method :super_bracket, :[]
 
   ##
   # Create a new TopN object.  Options available:
   #
   # @param [Hash] options the options used to configure the TopN object.
   #
-  # @option options [Fixnum] :maxsize The maximum number of keys to track.
+  # @option options [Fixnum] :maxkeys The maximum number of keys to track.
   #  Must be a positive Fixnum.  Defaults to 100.
   #
   # @option options [Symbol] :direction Configure the direction.
@@ -58,37 +51,37 @@ class TopN
   #   topn = TopN.new
   #
   # @example Create with a maximum size of 10, and track smaller values
-  #   topn = TopN.new(maxsize: 10, direction: :bottom)
+  #   topn = TopN.new(maxkeys: 10, direction: :bottom)
   #
-  def initialize(options = {})
+  def initialize(default = nil, options = {})
     options = {
-      maxsize: 100,
+      maxkeys: 100,
       direction: :top,
     }.merge(options)
 
     options.keys.each do |opt|
-      unless [:maxsize, :direction].include?opt
+      unless [:maxkeys, :direction].include?opt
         raise ArgumentError.new("invalid option #{opt}")
       end
     end
 
-    @maxsize = options[:maxsize]
+    @maxkeys = options[:maxkeys]
     @direction = options[:direction]
-    @data = {}
-    @size = 0
     @threshold_key = nil
 
     unless [:top, :bottom].include?(@direction)
       raise ArgumentError.new("direction must be :top or :bottom")
     end
 
-    unless @maxsize.is_a?Fixnum
-      raise ArgumentError.new("maxsize must be a Fixnum")
+    unless @maxkeys.is_a?Fixnum
+      raise ArgumentError.new("maxkeys must be a Fixnum")
     end
 
-    if @maxsize <= 0
-      raise ArgumentError.new("maxsize must be >= 1")
+    if @maxkeys <= 0
+      raise ArgumentError.new("maxkeys must be >= 1")
     end
+
+    super(default)
   end
 
   ##
@@ -105,11 +98,9 @@ class TopN
   # If an existing (key, value) is permitted, and will result in the list of
   # values at that key having the same value multiple times.
   #
-  # @return [Array] if the value was added to the key's list.
-  #
-  # @return [nil] if the value was not added because the key is too small or
-  # large to be tracked.
-  def add(key, value)
+  # @return [Object] the value passed in.  This will be returned even if
+  # the value is not added because there are too many keys already present.
+  def store(key, value)
     if @direction == :top
       add_top(key, value)
     else
@@ -117,23 +108,9 @@ class TopN
     end
   end
 
-  ##
-  # Find and return the list of values for a key.
-  #
-  # @return [Array<Object>] the list of values for 'key'.
-  #
-  # @return [nil] if the key does not exist.
-  def find(key)
-    @data[key]
-  end
-
-  ##
-  # Return the list of currently tracked keys.
-  #
-  # @return [Array<Object>] the list of values for this key.
-  #  Order is not guaranteed to match the oder which they were added.
-  def keys
-    @data.keys
+  # Behave like #store, with the same semantics.
+  def []=(key, value)
+    store(key, value)
   end
 
   private
@@ -143,21 +120,19 @@ class TopN
   def add_top(key, value)
     @threshold_key ||= key
 
-    if @data.has_key?key
-      @data[key] << value
+    if has_key?key
+      fetch(key) << value
     else
-      if @size >= @maxsize
-        return nil if key < @threshold_key
-        @data.delete(@threshold_key)
-        @size -= 1
-        @threshold_key = @data.keys.min
+      if size >= @maxkeys
+        return value if key < @threshold_key
+        delete(@threshold_key)
+        @threshold_key = keys.min
       end
-      @data[key] = [ value ]
-      @size += 1
+      super_store(key, [ value ])
       @threshold_key = key if key < @threshold_key
     end
 
-    @data[key]
+    value
   end
 
   ##
@@ -165,20 +140,18 @@ class TopN
   def add_bottom(key, value)
     @threshold_key ||= key
 
-    if @data.has_key?key
-      @data[key] << value
+    if has_key?key
+      fetch(key) << value
     else
-      if @size >= @maxsize
-        return nil if key > @threshold_key
-        @data.delete(@threshold_key)
-        @size -= 1
-        @threshold_key = @data.keys.max
+      if size >= @maxkeys
+        return value if key > @threshold_key
+        delete(@threshold_key)
+        @threshold_key = keys.max
       end
-      @data[key] = [ value ]
-      @size += 1
+      super_store(key, [ value ])
       @threshold_key = key if key > @threshold_key
     end
 
-    @data[key]
+    value
   end
 end

data/test/test_adding_bottom.rb

@@ -2,98 +2,98 @@ require 'helper'
 
 class TestAddingBottom < Minitest::Test
   def test_threshold_key_is_nil_on_create
-    topn = TopN.new(direction: :bottom)
+    topn = TopN.new(nil, direction: :bottom)
     assert_nil topn.threshold_key
   end
 
   def test_adding_updates_threshold_key
-    topn = TopN.new(direction: :bottom)
-    assert topn.add(5, 5), "add(5, 5) failed"
+    topn = TopN.new(nil, direction: :bottom)
+    topn[5] = 5
     assert_equal 5, topn.threshold_key
   end
 
   def test_adding_increments_size
-    topn = TopN.new(direction: :bottom)
-    assert topn.add(1, 1), "add(1, 1) failed"
+    topn = TopN.new(nil, direction: :bottom)
+    topn[1] = 1
     assert topn.size == 1, "size == 1 failed"
   end
 
   def test_adding_without_exceeding_adds
-    topn = TopN.new(direction: :bottom, maxsize: 10)
-    assert topn.add(5, 5), "add(5, 5) failed"
-    assert topn.find(5) == [5], "find(5) failed"
+    topn = TopN.new(nil, direction: :bottom, maxkeys: 10)
+    topn[5] = 5
+    assert_equal [5], topn[5]
     assert_equal 5, topn.threshold_key
   end
 
   def test_adding_sets_threshold_key
-    topn = TopN.new(direction: :bottom, maxsize: 10)
-    assert topn.add(5, 5), "add(5, 5) failed"
-    assert topn.find(5) == [5], "find(5) failed"
+    topn = TopN.new(nil, direction: :bottom, maxkeys: 10)
+    topn[5] = 5
+    assert_equal [5], topn[5]
     assert_equal 5, topn.threshold_key
   end
 
   def test_adding_without_exceeding
-    topn = TopN.new(direction: :bottom, maxsize: 10)
-    assert topn.add(5, 5), "add(5, 5) failed"
-    assert topn.add(10, 10), "add(10, 10) failed"
-    assert topn.find(5) == [5], "find(5) failed"
-    assert topn.find(10) == [10], "find(5) failed"
+    topn = TopN.new(nil, direction: :bottom, maxkeys: 10)
+    topn[5] = 5
+    topn[10] = 10
+    assert_equal [5], topn[5]
+    assert_equal [10], topn[10]
     assert_equal 10, topn.threshold_key
   end
 
   def test_adding_larger_without_exceeding_sets_threshold_key
-    topn = TopN.new(direction: :bottom, maxsize: 10)
-    assert topn.add(5, 5), "add(5, 5) failed"
+    topn = TopN.new(nil, direction: :bottom, maxkeys: 10)
+    topn[5] = 5
     assert_equal 5, topn.threshold_key
-    assert topn.add(10, 10), "add(10, 10) failed"
+    topn[10] = 10
     assert_equal 10, topn.threshold_key
   end
 
   def test_adding_smaller_without_exceeding_sets_threshold_key
-    topn = TopN.new(direction: :bottom, maxsize: 10)
-    assert topn.add(10, 10), "add(10, 10) failed"
+    topn = TopN.new(nil, direction: :bottom, maxkeys: 10)
+    topn[10] = 10
     assert_equal 10, topn.threshold_key
-    assert topn.add(5, 5), "add(5, 5) failed"
+    topn[5] = 5
     assert_equal 10, topn.threshold_key
   end
 
   def test_adding_two_values_to_the_same_key
-    topn = TopN.new(direction: :bottom, maxsize: 10)
-    assert topn.add(1, 1), "add(1, 1) failed"
-    assert topn.add(1, 2), "add(1, 2) failed"
-    assert_equal [1, 2], topn.find(1).sort
+    topn = TopN.new(nil, direction: :bottom, maxkeys: 10)
+    topn[1] = 1
+    topn[1] = 2
+    assert_equal [1, 2], topn[1].sort
   end
 
   def test_adding_smaller_key_when_limit_will_exceed
-    topn = TopN.new(direction: :bottom, maxsize: 2)
-    assert topn.add(3, 3), "add(3, 3) failed"
-    assert topn.add(2, 2), "add(2, 2) failed"
-    assert topn.add(1, 1), "add(1, 1) failed"
+    topn = TopN.new(nil, direction: :bottom, maxkeys: 2)
+    topn[3] = 3
+    topn[2] = 2
+    topn[1] = 1
     assert_equal 2, topn.size
-    assert_equal [1], topn.find(1)
-    assert_equal [2], topn.find(2)
-    assert_nil topn.find(3)
+    assert_equal [1], topn[1]
+    assert_equal [2], topn[2]
+    assert_nil topn[3]
   end
 
   def test_adding_larger_key_when_limit_will_exceed
-    topn = TopN.new(direction: :bottom, maxsize: 2)
-    assert topn.add(1, 1), "add(1, 1) failed"
-    assert topn.add(2, 2), "add(2, 2) failed"
-    assert_nil topn.add(3, 3)
+    topn = TopN.new(nil, direction: :bottom, maxkeys: 2)
+    topn[1] = 1
+    topn[2] = 2
+    topn[3] = 3
     assert_equal 2, topn.size
-    assert_equal [1], topn.find(1)
-    assert_equal [2], topn.find(2)
-    assert_nil topn.find(3)
+    assert_equal [1], topn[1]
+    assert_equal [2], topn[2]
+    assert_nil topn[3]
   end
 
   def test_torture
-    topn = TopN.new(direction: :bottom, maxsize: 10)
+    topn = TopN.new(nil, direction: :bottom, maxkeys: 10)
 
     records = []
     300_000.times do
       record = rand(4000)
       records << record
-      topn.add(record, rand(100_000_000))
+      topn[record] = rand(100_000_000)
     end
 
     top_records = records.uniq.sort[0..9]

data/test/test_adding_top.rb

@@ -8,92 +8,92 @@ class TestAddingTop < Minitest::Test
 
   def test_adding_updates_threshold_key
     topn = TopN.new
-    assert topn.add(5, 5), "add(5, 5) failed"
+    topn[5] = 5
     assert_equal 5, topn.threshold_key
   end
 
   def test_adding_increments_size
     topn = TopN.new
-    assert topn.add(1, 1), "add(1, 1) failed"
+    topn[1] = 1
     assert topn.size == 1, "size == 1 failed"
   end
 
   def test_adding_without_exceeding_adds
-    topn = TopN.new(maxsize: 10)
-    assert topn.add(5, 5), "add(5, 5) failed"
-    assert topn.find(5) == [5], "find(5) failed"
+    topn = TopN.new(nil, maxkeys: 10)
+    topn[5] = 5
+    assert_equal [5], topn[5]
     assert_equal 5, topn.threshold_key
   end
 
   def test_adding_sets_threshold_key
-    topn = TopN.new(maxsize: 10)
-    assert topn.add(5, 5), "add(5, 5) failed"
-    assert topn.find(5) == [5], "find(5) failed"
+    topn = TopN.new(nil, maxkeys: 10)
+    topn[5] = 5
+    assert_equal [5], topn[5]
     assert_equal 5, topn.threshold_key
   end
 
   def test_adding_without_exceeding
-    topn = TopN.new(maxsize: 10)
-    assert topn.add(5, 5), "add(5, 5) failed"
-    assert topn.add(10, 10), "add(10, 10) failed"
-    assert topn.find(5) == [5], "find(5) failed"
-    assert topn.find(10) == [10], "find(5) failed"
+    topn = TopN.new(nil, maxkeys: 10)
+    topn[5] = 5
+    topn[10] = 10
+    assert_equal [5], topn[5]
+    assert_equal [10], topn[10]
     assert_equal 5, topn.threshold_key
   end
 
   def test_adding_larger_without_exceeding_sets_threshold_key
-    topn = TopN.new(maxsize: 10)
-    assert topn.add(5, 5), "add(5, 5) failed"
+    topn = TopN.new(nil, maxkeys: 10)
+    topn[5] = 5
     assert_equal 5, topn.threshold_key
-    assert topn.add(10, 10), "add(10, 10) failed"
+    topn[10] = 10
     assert_equal 5, topn.threshold_key
   end
 
   def test_adding_smaller_without_exceeding_sets_threshold_key
-    topn = TopN.new(maxsize: 10)
-    assert topn.add(10, 10), "add(10, 10) failed"
+    topn = TopN.new(nil, maxkeys: 10)
+    topn[10] = 10
     assert_equal 10, topn.threshold_key
-    assert topn.add(5, 5), "add(5, 5) failed"
+    topn[5] = 5
     assert_equal 5, topn.threshold_key
   end
 
   def test_adding_two_values_to_the_same_key
-    topn = TopN.new(maxsize: 10)
-    assert topn.add(1, 1), "add(1, 1) failed"
-    assert topn.add(1, 2), "add(1, 2) failed"
-    assert_equal [1, 2], topn.find(1).sort
+    topn = TopN.new(nil, maxkeys: 10)
+    topn[1] = 1
+    topn[1] = 2
+    assert_equal [1, 2], topn[1].sort
   end
 
   def test_adding_larger_key_when_limit_will_exceed
-    topn = TopN.new(maxsize: 2)
-    assert topn.add(1, 1), "add(1, 1) failed"
-    assert topn.add(2, 2), "add(1, 1) failed"
-    assert topn.add(3, 3), "add(1, 1) failed"
+    topn = TopN.new(nil, maxkeys: 2)
+    topn[1] = 1
+    topn[2] = 2
+    topn[3] = 3
     assert_equal 2, topn.size
-    assert_nil topn.find(1)
-    assert_equal [2], topn.find(2)
-    assert_equal [3], topn.find(3)
+    assert_nil topn[1]
+    assert_equal [2], topn[2]
+    assert_equal [3], topn[3]
   end
 
   def test_adding_smaller_key_when_limit_will_exceed
-    topn = TopN.new(maxsize: 2)
-    assert topn.add(3, 3), "add(1, 1) failed"
-    assert topn.add(2, 2), "add(1, 1) failed"
-    assert_nil topn.add(1, 1)
+    topn = TopN.new(nil, maxkeys: 2)
+    topn[3] = 3
+    topn[2] = 2
+    topn[1] = 1
     assert_equal 2, topn.size
-    assert_nil topn.find(1)
-    assert_equal [2], topn.find(2)
-    assert_equal [3], topn.find(3)
+    assert_nil topn[1]
+    assert_equal [2], topn[2]
+    assert_equal [3], topn[3]
   end
 
   def test_torture
-    topn = TopN.new(maxsize: 1000)
+    topn = TopN.new(nil, maxkeys: 1000)
 
     records = []
     300_000.times do
       record = rand(4000)
       records << record
-      topn.add(record, rand(100_000_000))
+      topn[record] = rand(100_000_000)
     end
 
     top_records = records.uniq.sort { |a, b| b <=> a }[0..999]

data/test/test_creation.rb

@@ -6,48 +6,53 @@ class TestTopN < Minitest::Test
     assert topn
   end
 
-  def test_creation_without_arguments_sets_maxsize_to_some_positive_default
+  def test_creation_with_default_value
+    topn = TopN.new(:flarg)
+    assert_equal :flarg, topn[5]
+  end
+
+  def test_creation_without_arguments_sets_maxkeys_to_some_positive_default
     topn = TopN.new
-    assert topn.maxsize > 0
+    assert topn.maxkeys > 0
   end
 
-  def test_creation_with_maxsize
-    topn = TopN.new(maxsize: 100)
-    assert topn.maxsize == 100
+  def test_creation_with_maxkeys
+    topn = TopN.new(nil, maxkeys: 100)
+    assert topn.maxkeys == 100
   end
 
   def test_creation_with_direction
-    topn = TopN.new(direction: :bottom)
+    topn = TopN.new(nil, direction: :bottom)
     assert topn.direction == :bottom
   end
 
   def test_creation_raises_assertion_with_bad_direction
     assert_raises(ArgumentError) {
-      TopN.new(direction: :flarg)
+      TopN.new(nil, direction: :flarg)
     }
   end
 
-  def test_creation_raises_assertion_with_zero_maxsize
+  def test_creation_raises_assertion_with_zero_maxkeys
     assert_raises(ArgumentError) {
-      TopN.new(maxsize: 0)
+      TopN.new(nil, maxkeys: 0)
     }
   end
 
-  def test_creation_raises_assertion_with_negative_maxsize
+  def test_creation_raises_assertion_with_negative_maxkeys
     assert_raises(ArgumentError) {
-      TopN.new(maxsize: -1)
+      TopN.new(nil, maxkeys: -1)
     }
   end
 
-  def test_creation_raises_assertion_with_non_fixnum_maxsize
+  def test_creation_raises_assertion_with_non_fixnum_maxkeys
     assert_raises(ArgumentError) {
-      TopN.new(maxsize: 'foo')
+      TopN.new(nil, maxkeys: 'foo')
     }
   end
 
   def test_creation_raises_assertion_for_invalid_argument_names
     assert_raises(ArgumentError) {
-      TopN.new(flarg: 1)
+      TopN.new(nil, flarg: 1)
     }
   end
 end

data/test/test_data.rb

@@ -2,23 +2,23 @@ require 'helper'
 
 class TestData < Minitest::Test
   def test_data_is_empty_on_create
-    topn = TopN.new(maxsize: 2)
-    assert_equal({}, topn.data)
+    topn = TopN.new(nil, maxkeys: 2)
+    assert_equal({}, topn)
   end
 
-  def test_data_has_keys
-    topn = TopN.new(maxsize: 2)
-    assert topn.add(1, 1), "add(1, 1) failed"
-    assert topn.add(2, 2), "add(1, 1) failed"
-    assert topn.add(3, 3), "add(1, 1) failed"
-    assert_equal [2, 3], topn.data.keys.sort
+  def test_data
+    topn = TopN.new(nil, maxkeys: 2)
+    topn[1] = 1
+    topn[2] = 2
+    topn[3] = 3
+    assert_equal([ [2, [2]], [3, [ 3 ]] ], topn.sort)
   end
 
   def test_keys
-    topn = TopN.new(maxsize: 2)
-    assert topn.add(1, 1), "add(1, 1) failed"
-    assert topn.add(2, 2), "add(1, 1) failed"
-    assert topn.add(3, 3), "add(1, 1) failed"
+    topn = TopN.new(nil, maxkeys: 2)
+    topn[1] = 1
+    topn[2] = 2
+    topn[3] = 3
     assert_equal [2, 3], topn.keys.sort
   end
 end

data/top_n.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "top_n"
-  s.version = "1.0.1"
+  s.version = "1.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Michael Graff"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: top_n
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Michael Graff