data_structures_rmolinari 0.2.2 → 0.4.0

data/lib/data_structures_rmolinari/max_priority_search_tree.rb

@@ -1,30 +1,27 @@
+require 'must_be'
 require 'set'
 require_relative 'shared'
 
-
-# A priority search tree (PST) stores a set, P, of two-dimensional points (x,y) in a way that allows efficient answes to certain
+# A priority search tree (PST) stores a set, P, of two-dimensional points (x,y) in a way that allows efficient answers to certain
 # questions about P.
 #
-# (In the current implementation no two points can share an x-value and no two points can share a y-value. This (rather severe)
-# restriction can be relaxed with some more complicated code.)
-#
 # The data structure was introduced in 1985 by Edward McCreight. Later, De, Maheshwari, Nandy, and Smid showed how to construct a
 # PST in-place (using only O(1) extra memory), at the expense of some slightly more complicated code for the various supported
 # operations. It is their approach that we have implemented.
 #
 # The PST structure is an implicit, balanced binary tree with the following properties:
-# * The tree is a _max-heap_ in the y coordinate. That is, the point at each node has a y-value less than its parent.
+# * The tree is a _max-heap_ in the y coordinate. That is, the point at each node has a y-value no greater than its parent.
 # * For each node p, the x-values of all the nodes in the left subtree of p are less than the x-values of all the nodes in the right
 #   subtree of p. Note that this says nothing about the x-value at the node p itself. The tree is thus _almost_ a binary search tree
 #   in the x coordinate.
 #
 # Given a set of n points, we can answer the following questions quickly:
 #
-# - +leftmost_ne+: for x0 and y0, what is the leftmost point (x, y) in P satisfying x >= x0 and y >= y0?
-# - +rightmost_nw+: for x0 and y0, what is the rightmost point (x, y) in P satisfying x <= x0 and y >= y0?
-# - +highest_ne+: for x0 and y0, what is the highest point (x, y) in P satisfying x >= x0 and y >= y0?
-# - +highest_nw+: for x0 and y0, what is the highest point (x, y) in P satisfying x <= x0 and y >= y0?
-# - +highest_3_sided+: for x0, x1, and y0, what is the highest point (x, y) in P satisfying x >= x0, x <= x1 and y >= y0?
+# - +smallest_x_in_ne+: for x0 and y0, what is the leftmost point (x, y) in P satisfying x >= x0 and y >= y0?
+# - +largest_x_in_nw+: for x0 and y0, what is the rightmost point (x, y) in P satisfying x <= x0 and y >= y0?
+# - +largest_y_in_ne+: for x0 and y0, what is the highest point (x, y) in P satisfying x >= x0 and y >= y0?
+# - +largest_y_in_nw+: for x0 and y0, what is the highest point (x, y) in P satisfying x <= x0 and y >= y0?
+# - +largest_y_in_3_sided+: for x0, x1, and y0, what is the highest point (x, y) in P satisfying x >= x0, x <= x1 and y >= y0?
 # - +enumerate_3_sided+: for x0, x1, and y0, enumerate all points in P satisfying x >= x0, x <= x1 and y >= y0.
 #
 # (Here, "leftmost/rightmost" means "minimal/maximal x", and "highest" means "maximal y".)
@@ -33,11 +30,15 @@ require_relative 'shared'
 #
 # The final operation (enumerate) takes O(m + log n) time, where m is the number of points that are enumerated.
 #
+# In the current implementation no two points can share an x-value. This (rather severe) restriction can be relaxed with some more
+# complicated code, but it hasn't been written yet. See issue #9.
+#
+#
 # There is a related data structure called the Min-max priority search tree so we have called this a "Max priority search tree", or
 # MaxPST.
 #
 # References:
-# * E.M. McCreight, _Priority search trees_, SIAM J. Comput., 14(2):257-276, 1985.  Later, De,
+# * E.M. McCreight, _Priority search trees_, SIAM J. Comput., 14(2):257-276, 1985.
 # * M. De, A. Maheshwari, S. C. Nandy, M. Smid, _An In-Place Priority Search Tree_, 23rd Canadian Conference on Computational
 #   Geometry, 2011
 class DataStructuresRMolinari::MaxPrioritySearchTree
@@ -49,7 +50,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   # @param data [Array] the set P of points presented as an array. The tree is built in the array in-place without cloning.
   #   - Each element of the array must respond to +#x+ and +#y+.
   #     - This is not checked explicitly but a missing method exception will be thrown when we try to call one of them.
-  #   - The +x+ values must be distinct, as must the +y+ values. We raise a +Shared::DataError+ if this isn't the case.
+  #   - The +x+ values must be distinct. We raise a +Shared::DataError+ if this isn't the case.
   #     - This is a restriction that simplifies some of the algorithm code. It can be removed as the cost of some extra work. Issue
   #       #9.
   #
@@ -60,9 +61,8 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     @size = @data.size
 
     construct_pst
-    return unless verify
 
-    verify_properties
+    verify_properties if verify
   end
 
   ########################################
@@ -74,11 +74,11 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   # structure. Define p* as
   #
   # - (infty, -infty) if Q \intersect P is empty and
-  # - the highest (max-x) point in Q \intersect P otherwise.
+  # - the highest (max-y) point in Q \intersect P otherwise, breaking ties by preferring smaller values of x
   #
   # This method returns p* in O(log n) time and O(1) extra space.
-  def highest_ne(x0, y0)
-    highest_in_quadrant(x0, y0, :ne)
+  def largest_y_in_ne(x0, y0)
+    largest_y_in_quadrant(x0, y0, :ne)
   end
 
   # Return the highest point in P to the "northwest" of (x0, y0).
@@ -87,17 +87,17 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   # structure. Define p* as
   #
   # - (-infty, -infty) if Q \intersect P is empty and
-  # - the highest (max-y) point in Q \intersect P otherwise.
+  # - the highest (max-y) point in Q \intersect P otherwise, breaking ties by preferring smaller values of x
   #
   # This method returns p* in O(log n) time and O(1) extra space.
-  def highest_nw(x0, y0)
-    highest_in_quadrant(x0, y0, :nw)
+  def largest_y_in_nw(x0, y0)
+    largest_y_in_quadrant(x0, y0, :nw)
   end
 
-  # The basic algorithm is from De et al. section 3.1. We have generalaized it slightly to allow it to calculate both highest_ne and
-  # highest_nw
+  # The basic algorithm is from De et al. section 3.1. We have generalaized it slightly to allow it to calculate both largest_y_in_ne and
+  # largest_y_in_nw
   #
-  # Note that highest_ne(x0, y0) = highest_3_sided(x0, infinty, y0) so we don't really need this. But it's a bit faster than the
+  # Note that largest_y_in_ne(x0, y0) = largest_y_in_3_sided(x0, infinty, y0) so we don't really need this. But it's a bit faster than the
   # general case and is a simple algorithm that introduces a typical way that an algorithm interacts with the data structure.
   #
   # From the paper:
@@ -108,17 +108,17 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   #     - If Q intersect P is empty then p* = best
   #
   # Here, P is the set of points in our data structure and T_p is the subtree rooted at p
-  private def highest_in_quadrant(x0, y0, quadrant)
+  private def largest_y_in_quadrant(x0, y0, quadrant)
     quadrant.must_be_in [:ne, :nw]
 
     p = root
     if quadrant == :ne
-      best = Pair.new(INFINITY, -INFINITY)
+      best = Point.new(INFINITY, -INFINITY)
       preferred_child = ->(n) { right(n) }
       nonpreferred_child = ->(n) { left(n) }
       sufficient_x = ->(x) { x >= x0 }
     else
-      best = Pair.new(-INFINITY, -INFINITY)
+      best = Point.new(-INFINITY, -INFINITY)
       preferred_child = ->(n) { left(n) }
       nonpreferred_child = ->(n) { right(n) }
       sufficient_x = ->(x) { x <= x0 }
@@ -135,10 +135,10 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     #
     #   takes as input a point t and does the following: if t \in Q and y(t) > y(best) then it assignes best = t
     #
-    # Note that the paper identifies a node in the tree with its value. We need to grab the correct node.
+    # We break ties by preferring points with smaller x values
     update_highest = lambda do |node|
       t = @data[node]
-      if in_q.call(t) && t.y > best.y
+      if in_q.call(t) && (t.y > best.y || (t.y == best.y && t.x < best.x))
         best = t
       end
     end
@@ -194,7 +194,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   # - the leftmost (min-x) point in Q \intersect P otherwise.
   #
   # This method returns p* in O(log n) time and O(1) extra space.
-  def leftmost_ne(x0, y0)
+  def smallest_x_in_ne(x0, y0)
     extremal_in_x_dimension(x0, y0, :ne)
   end
 
@@ -207,14 +207,14 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   # - the leftmost (min-x) point in Q \intersect P otherwise.
   #
   # This method returns p* in O(log n) time and O(1) extra space.
-  def rightmost_nw(x0, y0)
+  def largest_x_in_nw(x0, y0)
     extremal_in_x_dimension(x0, y0, :nw)
   end
 
-  # A genericized version of the paper's leftmost_ne that can calculate either leftmost_ne or rightmost_nw as specifies via a
+  # A genericized version of the paper's smallest_x_in_ne that can calculate either smallest_x_in_ne or largest_x_in_nw as specifies via a
   # parameter.
   #
-  # Quadrant is either :ne (which gives leftmost_ne) or :nw (which gives rightmost_nw).
+  # Quadrant is either :ne (which gives smallest_x_in_ne) or :nw (which gives largest_x_in_nw).
   #
   # From De et al:
   #
@@ -228,10 +228,10 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
 
     if quadrant == :ne
       sign = 1
-      best = Pair.new(INFINITY, INFINITY)
+      best = Point.new(INFINITY, INFINITY)
     else
       sign = -1
-      best = Pair.new(-INFINITY, INFINITY)
+      best = Point.new(-INFINITY, INFINITY)
     end
 
     p = q = root
@@ -245,7 +245,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     #   takes as input a point t and does the following: if t \in Q and x(t) < x(best) then it assignes best = t
     #
     # Note that the paper identifies a node in the tree with its value. We need to grab the correct node.
-    update_leftmost = lambda do |node|
+    update_best = lambda do |node|
       t = @data[node]
       if in_q.call(t) && sign * t.x < sign * best.x
         best = t
@@ -261,13 +261,13 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     #
     # - If x0 <= x(c1) then all subtrees have large enough x values and we look for the leftmost node in c with a large enough y
     #   value. Both p and q are sent into that subtree.
-    # - If x0 >= x(ck) the the rightmost subtree is our only hope the rightmost subtree.
+    # - If x0 >= x(ck) the the rightmost subtree is our only hope
     # - Otherwise, x(c1) < x0 < x(ck) and we let i be least so that x(ci) <= x0 < x(c(i+1)). Then q becomes the lefmost cj in c not
     #   to the left of ci such that y(cj) >= y0, if any. p becomes ci if y(ci) >= y0 and q otherwise. If there is no such j, we put
     #   q = p. This may leave both of p, q undefined which means there is no useful way forward and we return nils to signal this to
     #   calling code.
     #
-    # The same logic applies to rightmost_nw, though everything is "backwards"
+    # The same logic applies to largest_x_in_nw, though everything is "backwards"
     # - membership of Q depends on having a small-enough value of x, rather than a large-enough one
     # - among the ci, values towards the end of the array tend not to be in Q while values towards the start of the array tend to be
     #  in Q
@@ -302,14 +302,14 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
       new_p ||= new_q # if nodes[i] is no good, send p along with q
       new_q ||= new_p # but if there is no worthwhile value for q we should send it along with p
 
-      return [new_q, new_p] if quadrant == :nw # swap for the rightmost_nw case.
+      return [new_q, new_p] if quadrant == :nw # swap for the largest_x_in_nw case.
 
       [new_p, new_q]
     end
 
     until leaf?(p)
-      update_leftmost.call(p)
-      update_leftmost.call(q)
+      update_best.call(p)
+      update_best.call(q)
 
       if p == q
         if one_child?(p)
@@ -324,7 +324,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
           q = p # p itself is just one layer above the leaves, or is itself a leaf
         elsif one_child?(q)
           # This generic approach is not as fast as the bespoke checks described in the paper. But it is easier to maintain the code
-          # this way and allows easy implementation of rightmost_nw
+          # this way and allows easy implementation of largest_x_in_nw
           p, q = determine_next_nodes.call(left(p), right(p), left(q))
         else
           p, q = determine_next_nodes.call(left(p), right(p), left(q), right(q))
@@ -332,8 +332,8 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
         break unless p # we've run out of useful nodes
       end
     end
-    update_leftmost.call(p) if p
-    update_leftmost.call(q) if q
+    update_best.call(p) if p
+    update_best.call(q) if q
     best
   end
 
@@ -346,10 +346,10 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   # MaxPST. (Note that Q is empty if x1 < x0.) Define p* as
   #
   # - (infty, -infty) if Q \intersect P is empty and
-  # - the highest (max-x) point in Q \intersect P otherwise.
+  # - the highest (max-y) point in Q \intersect P otherwise, breaking ties by preferring smaller x values.
   #
   # This method returns p* in O(log n) time and O(1) extra space.
-  def highest_3_sided(x0, x1, y0)
+  def largest_y_in_3_sided(x0, x1, y0)
     # From the paper:
     #
     #    The three real numbers x0, x1, and y0 define the three-sided range Q = [x0,x1] X [y0,∞). If Q \intersect P̸ is not \empty,
@@ -373,7 +373,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     #
     # Sometimes we don't have a relevant node to the left or right of Q. The booleans L and R (which we call left and right) track
     # whether p and q are defined at the moment.
-    best = Pair.new(INFINITY, -INFINITY)
+    best = Point.new(INFINITY, -INFINITY)
     p = q = left = right = nil
 
     x_range = (x0..x1)
@@ -389,7 +389,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     # Note that the paper identifies a node in the tree with its value. We need to grab the correct node.
     update_highest = lambda do |node|
       t = @data[node]
-      if in_q.call(t) && t.y > best.y
+      if in_q.call(t) && (t.y > best.y || (t.y == best.y && t.x < best.x))
         best = t
       end
     end
@@ -570,7 +570,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     # My high-level understanding of the algorithm
     # --------------------------------------------
     #
-    # We need to find all elements of Q \intersect P, so it isn't enough, as it was in highest_3_sided simply to keep track of p and
+    # We need to find all elements of Q \intersect P, so it isn't enough, as it was in largest_y_in_3_sided simply to keep track of p and
     # q. We need to track four nodes, p, p', q', and q which are (with a little handwaving) respectively
     #
     # - the rightmost node to the left of Q' = [x0, x1] X [-infinity, infinity],
@@ -641,7 +641,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
           end
           current = parent(current)
         else
-          raise LogicError, "Explore(t) state is somehow #{state} rather than 0, 1, or 2."
+          raise InternalLogicError, "Explore(t) state is somehow #{state} rather than 0, 1, or 2."
         end
       end
     end
@@ -692,8 +692,6 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     # The four key helpers described in the paper
 
     # Handle the next step of the subtree at p
-    #
-    # I need to go through this with paper, pencil, and some diagrams.
     enumerate_left = lambda do
       if leaf?(p)
         left = false
@@ -786,7 +784,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
             p_in = right(p_in)
             left = true
           else
-            raise LogicError, 'q_in cannot be active, by the value in the right child of p_in!' if right_in
+            raise InternalLogicError, 'q_in cannot be active, by the value in the right child of p_in!' if right_in
 
             p = left(p_in)
             q = right(p_in)
@@ -796,7 +794,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
           end
         elsif left_val.x <= x1
           if right_val.x > x1
-            raise LogicError, 'q_in cannot be active, by the value in the right child of p_in!' if right_in
+            raise InternalLogicError, 'q_in cannot be active, by the value in the right child of p_in!' if right_in
 
             q = right(p_in)
             p_in = left(p_in)
@@ -810,7 +808,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
             right_in = true
           end
         else
-          raise LogicError, 'q_in cannot be active, by the value in the right child of p_in!' if right_in
+          raise InternalLogicError, 'q_in cannot be active, by the value in the right child of p_in!' if right_in
 
           q = left(p_in)
           deactivate_p_in.call
@@ -846,8 +844,8 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
 
       # q has two children. Cases!
       if @data[left(q)].x < x0
-        raise LogicError, 'p_in should not be active, based on the value at left(q)' if left_in
-        raise LogicError, 'q_in should not be active, based on the value at left(q)' if right_in
+        raise InternalLogicError, 'p_in should not be active, based on the value at left(q)' if left_in
+        raise InternalLogicError, 'q_in should not be active, based on the value at left(q)' if right_in
 
         left = true
         if @data[right(q)].x < x0
@@ -878,7 +876,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
 
     # Given: q' is active and satisfied x0 <= x(q') <= x1
     enumerate_right_in = lambda do
-      raise LogicError, 'right_in should be true if we call enumerate_right_in' unless right_in
+      raise InternalLogicError, 'right_in should be true if we call enumerate_right_in' unless right_in
 
       if @data[q_in].y >= y0
         report.call(q_in)
@@ -910,7 +908,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
       # q' has two children
       right_val = @data[right(q_in)]
       if left_val.x < x0
-        raise LogicError, 'p_in cannot be active, by the value in the left child of q_in' if left_in
+        raise InternalLogicError, 'p_in cannot be active, by the value in the left child of q_in' if left_in
 
         if right_val.x < x0
           p = right(q_in)
@@ -970,7 +968,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
 
     while left || left_in || right_in || right
       # byebug if $do_it
-      raise LogicError, 'It should not be that q_in is active but p_in is not' if right_in && !left_in
+      raise InternalLogicError, 'It should not be that q_in is active but p_in is not' if right_in && !left_in
 
       set_i = []
       set_i << :left if left
@@ -988,7 +986,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
       when :right
         enumerate_right.call
       else
-        raise LogicError, "bad symbol #{z}"
+        raise InternalLogicError, "bad symbol #{z}"
       end
     end
     return result unless block_given?
@@ -999,13 +997,14 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
 
   private def construct_pst
     raise DataError, 'Duplicate x values are not supported' if contains_duplicates?(@data, by: :x)
-    raise DataError, 'Duplicate y values are not supported' if contains_duplicates?(@data, by: :y)
 
-    # We follow the algorithm in the paper by De, Maheshwari et al.
+    # We follow the algorithm in the paper by De, Maheshwari et al, which takes O(n log^2 n) time. Their follow-up paper that
+    # defines the Min-max PST, describes how to do the construction in O(n log n) time, but it is more complex and probably not
+    # worth the trouble of both a bespoke heapsort the special sorting algorithm of Katajainen and Pasanen.
 
-    # Since we are building an implicit binary tree, things are simpler if the array is 1-based. This probably requires a malloc and
-    # data copy, which isn't great, but it's in the C layer so cheap compared to the O(n log^2 n) work we need to do for
-    # construction. In fact, we are probably doing O(n^2) work because of all the calls to #index_with_largest_y_in.
+    # Since we are building an implicit binary tree, things are simpler if the array is 1-based. This requires a malloc (perhaps)
+    # and memcpy (for sure), which isn't great, but it's in the C layer so cheap compared to the O(n log^2 n) work we need to do for
+    # construction.
     @data.unshift nil
 
     h = Math.log2(@size).floor
@@ -1052,63 +1051,14 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
     end
   end
 
-  ########################################
-  # Tree arithmetic
-
-  # # First element and root of the tree structure
-  # private def root
-  #   1
-  # end
-
-  # # Indexing is from 1
-  # private def parent(i)
-  #   i >> 1
-  # end
-
-  # private def left(i)
-  #   i << 1
-  # end
-
-  # private def right(i)
-  #   1 + (i << 1)
-  # end
-
-  # private def level(i)
-  #   l = 0
-  #   while i > root
-  #     i >>= 1
-  #     l += 1
-  #   end
-  #   l
-  # end
-
-  # # i has no children
-  # private def leaf?(i)
-  #   i > @last_non_leaf
-  # end
-
-  # # i has exactly one child (the left)
-  # private def one_child?(i)
-  #   i == @parent_of_one_child
-  # end
-
-  # # i has two children
-  # private def two_children?(i)
-  #   i <= @last_parent_of_two_children
-  # end
-
-  # # i is the left child of its parent.
-  # private def left_child?(i)
-  #   (i & 1).zero?
-  # end
-
   private def swap(index1, index2)
     return if index1 == index2
 
     @data[index1], @data[index2] = @data[index2], @data[index1]
   end
 
-  # The index in @data[l..r] having the largest value for y
+  # The index in @data[l..r] having the largest value for y, breaking ties with the smaller x value. Since we are already sorted by
+  # x we don't actually need to check this.
   private def index_with_largest_y_in(l, r)
     return nil if r < l
 
@@ -1134,7 +1084,8 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
   private def verify_properties
     # It's a max-heap in y
     (2..@size).each do |node|
-      raise LogicError, "Heap property violated at child #{node}" unless @data[node].y < @data[parent(node)].y
+      byebug unless @data[node].y <= @data[parent(node)].y
+      raise InternalLogicError, "Heap property violated at child #{node}" unless @data[node].y <= @data[parent(node)].y
     end
 
     # Left subtree has x values less than all of the right subtree
@@ -1144,7 +1095,7 @@ class DataStructuresRMolinari::MaxPrioritySearchTree
       left_max = max_x_in_subtree(left(node))
       right_min = min_x_in_subtree(right(node))
 
-      raise LogicError, "Left-right property of x-values violated at #{node}" unless left_max < right_min
+      raise InternalLogicError, "Left-right property of x-values violated at #{node}" unless left_max < right_min
     end
   end
 

data/lib/data_structures_rmolinari/shared.rb

@@ -1,11 +1,19 @@
 # Some odds and ends shared by other classes
 module Shared
+  # Infinity without having to put a +Float::+ prefix every time
   INFINITY = Float::INFINITY
 
-  Pair = Struct.new(:x, :y)
+  # An (x, y) coordinate pair.
+  Point = Struct.new(:x, :y)
 
   # @private
+
+  # Used for errors related to logic errors in client code
   class LogicError < StandardError; end
+  # Used for errors related to logic errors in library code
+  class InternalLogicError < LogicError; end
+
+  # Used for errors related to data, such as duplicated elements where they must be distinct.
   class DataError < StandardError; end
 
   # @private

data/lib/data_structures_rmolinari.rb

@@ -1,7 +1,10 @@
+require 'forwardable'
+
 require_relative 'data_structures_rmolinari/shared'
 
 module DataStructuresRMolinari
-  Pair = Shared::Pair
+  # A struct responding to +.x+ and +.y+.
+  Point = Shared::Point
 end
 
 # These define classes inside module DataStructuresRMolinari
@@ -9,15 +12,16 @@ require_relative 'data_structures_rmolinari/disjoint_union'
 require_relative 'data_structures_rmolinari/generic_segment_tree'
 require_relative 'data_structures_rmolinari/heap'
 require_relative 'data_structures_rmolinari/max_priority_search_tree'
-require_relative 'data_structures_rmolinari/minmax_priority_search_tree'
 
+# A namespace to hold the provided classes. We want to avoid polluting the global namespace with names like "Heap"
 module DataStructuresRMolinari
   ########################################
   # Concrete instances of Segment Tree
   #
-  # @todo consider moving these into generic_segment_tree.rb
+  # @todo consider moving these into generic_segment_tree.rb and renaming that file
 
-  # Takes an array A(0...n) and tells us what the maximum value is on a subinterval A(i..j) in O(log n) time.
+  # A segment tree that for an array A(0...n) answers questions of the form "what is the maximum value in the subinterval A(i..j)?"
+  # in O(log n) time.
   class MaxValSegmentTree
     extend Forwardable
 
@@ -25,28 +29,27 @@ module DataStructuresRMolinari
     def_delegator :@structure, :update_at
 
     # @param data an object that contains values at integer indices based at 0, via +data[i]+.
-    #   - The usual use case will be an Array, but it could also be a hash or a proc of some sort.
+    #   - This will usually be an Array, but it could also be a hash or a proc.
     def initialize(data)
-      @structure = GenericSegmentTree.new(
+      @structure = SegmentTreeTemplate.new(
         combine:               ->(a, b) { [a, b].max },
         single_cell_array_val: ->(i) { data[i] },
         size:                  data.size,
-        identity:              -Float::INFINITY
+        identity:              -Shared::INFINITY
       )
     end
 
-    # The maximum value in A(i..j)
+    # The maximum value in A(i..j).
     #
     # The arguments must be integers in 0...(A.size)
-    # @return the largest value in A(i..j).
-    #   - Return +nil+ if i > j
+    # @return the largest value in A(i..j) or -Infinity if i > j.
     def max_on(i, j)
       @structure.query_on(i, j)
     end
   end
 
-  # A segment tree that for an array A(0...n) efficiently answers questions of the form "what is the index of the maximal value in
-  # a subinterval A(i..j) in O(log n) time.
+  # A segment tree that for an array A(0...n) answers questions of the form "what is the index of the maximal value in the
+  # subinterval A(i..j)?" in O(log n) time.
   class IndexOfMaxValSegmentTree
     extend Forwardable
 
@@ -55,7 +58,7 @@ module DataStructuresRMolinari
 
     # @param (see MaxValSegmentTree#initialize)
     def initialize(data)
-      @structure = GenericSegmentTree.new(
+      @structure = SegmentTreeTemplate.new(
         combine:               ->(p1, p2) { p1[1] >= p2[1] ? p1 : p2 },
         single_cell_array_val: ->(i) { [i, data[i]] },
         size:                  data.size,
@@ -66,7 +69,7 @@ module DataStructuresRMolinari
     # The index of the maximum value in A(i..j)
     #
     # The arguments must be integers in 0...(A.size)
-    # @return (Integer, nil) the index of the largest value in A(i..j).
+    # @return (Integer, nil) the index of the largest value in A(i..j) or +nil+ if i > j.
     #   - If there is more than one entry with that value, return one the indices. There is no guarantee as to which one.
     #   - Return +nil+ if i > j
     def index_of_max_val_on(i, j)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_structures_rmolinari
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Rory Molinari
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-06 00:00:00.000000000 Z
+date: 2023-01-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: must_be
@@ -80,12 +80,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - lib/data_structures_rmolinari.rb
 - lib/data_structures_rmolinari/disjoint_union.rb
 - lib/data_structures_rmolinari/generic_segment_tree.rb
 - lib/data_structures_rmolinari/heap.rb
 - lib/data_structures_rmolinari/max_priority_search_tree.rb
-- lib/data_structures_rmolinari/minmax_priority_search_tree.rb
 - lib/data_structures_rmolinari/shared.rb
 homepage: https://github.com/rmolinari/data_structures
 licenses: