data_structures_rmolinari 0.5.7 → 0.5.8

data/lib/data_structures_rmolinari/algorithms.rb

@@ -15,7 +15,7 @@ module DataStructuresRMolinari::Algorithms
   # Maheshwari, A., Nandy, S. C., Smid, M., _An In-Place Min-max Priority Search Tree_, Computational Geometry, v46 (2013), pp
   # 310-327.
   #
-  # It runs in O(m log n) time, where m is the number of MERs enumerated and n is the number of points in P.  (Contructing the
+  # It runs in O(m log n) time, where m is the number of MERs enumerated and n is the number of points in P.  (Constructing the
   # MaxPST takes O(n log^2 n) time, but m = O(n^2) so we are still O(m log n) overall.)
   #
   # @param points [Array] an array of points in the x-y plane. Each must respond to +x+ and +y+.
@@ -30,6 +30,8 @@ module DataStructuresRMolinari::Algorithms
     sorted_points = points.sort_by(&:x)
     x_min = sorted_points.first.x
     x_max = sorted_points.last.x
+
+    # This is O(n).  But it also O(m) beacause consecutive pairs of points produce a type 1 rectangle.
     y_min, y_max = sorted_points.map(&:y).minmax
 
     # Enumerate type 1
@@ -94,4 +96,35 @@ module DataStructuresRMolinari::Algorithms
       end
     end
   end
+
+  # Given an enumerable and a number k, return the k smallest items from the enumerable in ascending order.
+  #
+  # If a block is given, each element is yielded to the block to determin its sort key.  Otherwise each element is its own sort key.
+  #
+  # We use a heap of size k.  Run time is O(n log k).
+  #
+  # TODO: offer to return the best k items unsorted, which will be slightly faster.  This requires changing Heap to produce the
+  # contents all at once.  Probably not worth the trouble.
+  def self.first_k(enumerable, k, &block)
+    heap = DataStructuresRMolinari::Heap.new(max_heap: true, addressable: false)
+
+    enumerable.each do |item|
+      priority = if block_given?
+        yield item
+      else
+        item
+      end
+
+      if heap.size < k
+        heap.insert(item, priority)
+      elsif priority < heap.top_priority
+        heap.pop
+        heap.insert(item, priority)
+      end
+    end
+
+    result = []
+    result << heap.pop until heap.empty?
+    result.reverse
+  end
 end

data/lib/data_structures_rmolinari/heap.rb

@@ -42,7 +42,8 @@ require_relative 'shared'
 #   DOI 10.1007/s00224-017-9760-2
 #
 # @todo
-#   - let caller see the priority of the top element. Maybe this is useful sometimes.
+#   - allow a priority-calculation lambda to be specified at construction. This would mean client code doesn't have to worry about
+#     it.
 class DataStructuresRMolinari::Heap
   include Shared
   include Shared::BinaryTreeArithmetic

data/lib/data_structures_rmolinari/max_priority_search_tree.rb

@@ -87,7 +87,7 @@ require_relative 'shared'
 #
 # So, we may say that queries on open regions will work as expected if either
 # - all coordinates of the points in the PST are finite Ruby Floats, or
-# - all coordinates of the points are finite Numeric values and for no such pair of x-values s, t (or pair of y-values) is it such
+# - all coordinates of the points are finite Numeric values and for no such pair of x-values s < t (or pair of y-values) is it true
 #   that +s.to_f.next_float > t+.
 #
 # Otherwise, use this functionality at your own risk, and not at all with coordinates that do not respond reasonably to +to_f+.

data/lib/data_structures_rmolinari/min_priority_search_tree.rb

@@ -22,7 +22,8 @@ require_relative 'shared'
 #   et al. But we don't do that, as we create a separate array of Points.
 # - Whereas the implementation of MaxPST means that client code gets the same (x, y) objects back in results as it passed into the
 #   contructor, that's not the case here.
-#   - we map each point in the input - which is an object responding to +#x+ and +#y+ - to an instance of +Point+, and will return (different) instances of +Point+ in response to queries.
+#   - we map each point in the input - which is an object responding to +#x+ and +#y+ - to an instance of +Point+, and will return
+#     (different) instances of +Point+ in response to queries.
 #   - client code is unlikely to care, but be aware of this, just in case.
 #
 # Given a set of n points, we can answer the following questions quickly:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_structures_rmolinari
 version: !ruby/object:Gem::Version
-  version: 0.5.7
+  version: 0.5.8
 platform: ruby
 authors:
 - Rory Molinari
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-04 00:00:00.000000000 Z
+date: 2025-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: must_be
@@ -122,7 +122,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.5
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: Several miscellaneous data structures I have implemented to learn about them.