data_structures_rmolinari 0.4.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 943ac55678a074cc0da3667dccbb07ee7d203639233f53bd8587af7fd8cd062e
-  data.tar.gz: ad235e5f4714e699f1cf5f113dd4b3a356a194cced5a74b60e17c5e3a896e01b
+  metadata.gz: 7682f6d3b0779f347ce0797f55f33b9d7dcc7bd9c2039fc2fd6f865eb72e085a
+  data.tar.gz: d717e5e36f79ddc4ecb605a59b475b7114359dea7476445590deb300f7915bd4
 SHA512:
-  metadata.gz: a68de76c88c67fadc42752610c695b1f0b8fd17f34db9c806291aeab4c933fe84c6523615deb4197e1c9fa6d36dce30987cc4e8896a2b0c1700b7e72b5bd2fff
-  data.tar.gz: 9063d89a98d599f27db2585bf383dbfb13e8f927abce64ac7eafb2edd70c490ddad1f1fc51e0f11c24adf29f28ab8c56548a6db264b15ace239c63b1a2ce5a01
+  metadata.gz: c3ffd9a4f67f55b7a2df1c949cf2288c06fcae416d5ff03a10307a1b79c3dae1daa74e2576d5e190c989adeea47b046426fad8c3c64199aadf22ba500b317f36
+  data.tar.gz: 8380d6117f2955da9362395f8315f5121b4f7afba2f69aabb1981a01b675cbbed81d07c10b5745409080c2588c92df3d676ec36efa128571234a74dceef0e20d

data/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [0.5.0] 2023-02.03
+
+- SegmentTree
+  - Reorganize the code into a SegmentTree submodule.
+  - Provide a conveniece method for getting concrete instances.
+
+- README.md
+  - Add some simple example code for the data types.
+
+## [0.4.4] 2023-02-02
+
 - Disjoint Union
   - C extension: use Convenient Containers rather than my janky Dynamic Array attempt.
 

data/README.md

@@ -14,18 +14,6 @@ The code is available as a gem: https://rubygems.org/gems/data_structures_rmolin
 The right way to organize the code is not obvious to me. For now the data structures are all defined in the module
 `DataStructuresRMolinari` to avoid polluting the global namespace.
 
-Example usage after the gem is installed:
-```
-require 'data_structures_rmolinari`
-
-# Pull what we need out of the namespace
-MaxPrioritySearchTree = DataStructuresRMolinari::MaxPrioritySearchTree
-Point = DataStructuresRMolinari::Point # anything responding to :x and :y is fine
-
-pst = MaxPrioritySearchTree.new([Point.new(1, 1)])
-puts pst.largest_y_in_ne(0, 0) # "Point(1,1)"
-```
-
 # Implementations
 
 ## Disjoint Union
@@ -42,6 +30,23 @@ It also provides
 For more details see https://en.wikipedia.org/wiki/Disjoint-set_data_structure and the paper [[TvL1984]](#references) by Tarjan and
 van Leeuwen.
 
+``` ruby
+require 'data_structures_rmolinari'
+DisjointUnion = DataStructuresRMolinari::DisjointUnion
+
+# Create an instance over the "universe" 0, 1, ..., 9.
+du = DisjointUnion.new(10)
+du.subset_count          # => 10; each element starts out in its own subset
+
+du.unite(2, 3)           # say that 2 and 3 are actually in the same subset
+du.subset_count          # => 9
+du.find(2) == du.find(3) # => true
+
+du.unite(4, 5)
+du.unite(3, 4)           # now 2, 3, 4, and 5 are all in the same subset
+du.subset_count          # => 7
+```
+
 ## Heap
 
 This is a standard binary heap with an `update` method, suitable for use as a priority queue. There are several supported
@@ -63,6 +68,24 @@ allows the insertion of duplicate items (which is sometimes useful) and slightly
 
 See https://en.wikipedia.org/wiki/Binary_heap and the paper by Edelkamp, Elmasry, and Katajainen [[EEK2017]](#references).
 
+``` ruby
+require 'data_structures_rmolinari'
+Heap = DataStructuresRMolinari::Heap
+
+data = [4, 3, 2, 1]
+
+heap = Heap.new
+
+# Insert the elements of data, each with itself as priority.
+data.each { |v| heap.insert(v, v) }
+
+heap.top           # => 1, since we have a min-heap.
+heap.pop           # => 1
+heap.top           # => 2; with 1 gone, this is the element with least priority
+heap.update(3, -3)
+heap.top           # => 3; now 3 is the element with least priority
+```
+
 ## Priority Search Tree
 
 A PST stores a set P of two-dimensional points in a way that allows certain queries about P to be answered efficiently. The data
@@ -96,13 +119,27 @@ regions.
 By default these data structures are immutable: once constructed they cannot be changed. But there is a constructor option that
 makes the instance "dynamic". This allows us to delete the element at the root of the tree - the one with largest y value (smallest
 for MinPST) - with the `delete_top!` method. This operation is important in certain algorithms, such as enumerating all maximal
-empty rectangles (see the second paper by De et al.[[DMNS2013]](#references)) Note that points can still not be added to the PST in
+empty rectangles (see the second paper by De et al[[DMNS2013]](#references)). Note that points can still not be added to the PST in
 any case, and choosing the dynamic option makes certain internal bookkeeping operations slower.
 
 In [[DMNS2013]](#references) De et al. generalize the in-place structure to a _Min-max Priority Search Tree_ (MinmaxPST) that can
 answer queries in all four quadrants and both "kinds" of 3-sided boxes. Having one of these would save the trouble of constructing
 both a MaxPST and MinPST. But the presentiation is hard to follow in places and the paper's pseudocode is buggy.[^minmaxpst]
 
+``` ruby
+require 'data_structures_rmolinari'
+MaxPST = DataStructuresRMolinari::MaxPrioritySearchTree
+Point = Shared::Point # simple (x, y) struct. Anything responding to #x and #y will work
+
+data = [Point.new(0, 0), Point.new(1, 2), Point.new(2, 1)]
+pst = MaxPST.new(data)
+
+pst.largest_y_in_ne(0, 0)              # => #<struct Shared::Point x=1, y=2>
+pst.largest_y_in_ne(1, 1)              # => #<struct Shared::Point x=1, y=2>
+pst.largest_y_in_ne(1.5, 1)            # => #<struct Shared::Point x=2, y=1>
+pst.largest_y_in_3_sided(-0.5, 0.5, 0) # => #<struct Shared::Point x=0, y=0>
+```
+
 ## Segment Tree
 
 A segment tree stores information related to subintervals of a certain array. For example, a segment tree can be used to find the
@@ -112,11 +149,37 @@ arbitrary subarrays.
 
 An excellent description of the idea is found at https://cp-algorithms.com/data_structures/segment_tree.html.
 
-Generic code is provided in `SegmentTreeTemplate`. Concrete classes provide a handful of simple lambdas and constants to the
-template class's initializer. Figuring out the details requires some knowledge of the internal mechanisms of a segment tree, for
-which the link at cp-algorithms.com is very helpful. See the definitions of the concrete classes `MaxValSegmentTree` and
+Generic code is provided in `SegmentTree::SegmentTreeTemplate` and its equivalent (and faster) C-based sibling,
+`SegmentTree::CSegmentTreeTemplate` (see [below](#c-extensions)).
+
+Writing a concrete segment tree class just means providing some simple lambdas and constants to the template class's
+initializer. Figuring out the details requires some knowledge of the internal mechanisms of a segment tree, for which the link at
+cp-algorithms.com is very helpful. See the implementations of the concrete classes `MaxValSegmentTree` and
 `IndexOfMaxValSegmentTree` for examples.
 
+Since there are several concrete "types" and two underlying generic implementions there is a convenience method on the `SegmentTree`
+module to get instances.
+
+``` ruby
+require 'data_structures_rmolinari'
+SegmentTree = DataStructuresRMolinari::SegmentTree # namespace module
+
+data = [1, -3, 2, 1, 5, -9]
+
+# Get a segment tree instance that will answer "max over this subinterval" questions about data.
+# Here we get one using the ruby implementation of the generic functionality.
+#
+# We offer :index_of_max as an alternative to :max. This will construct an instance that answers
+# questions of the form "an index of the maximum value over this subinterval".
+#
+# To use the version written in C, put :c instead of :ruby.
+seg_tree = SegmentTree.construct(data, :max, :ruby)
+
+seg_tree.max_on(0, 2) # => 2
+seg_tree.max_on(1, 4) # => 5
+# ..etc..
+```
+
 ## Algorithms
 
 The Algorithms submodule contains some algorithms using the data structures.
@@ -130,13 +193,12 @@ The Algorithms submodule contains some algorithms using the data structures.
 
 # C Extensions
 
-As another learning process I have implemented several of these data structures as C extensions. The class names have a "C" prefixed
-and they can be required like their pure Ruby versions. They have the same APIs as their Ruby cousins.
+As another learning process I have implemented several of these data structures as C extensions. The APIs are the same.
 
 ## Disjoint Union
 
-A benchmark suggests that a long sequence of `unite` operations is about 3 times as fast with the `CDisjointUnion` as with
-`DisjointUnion`.
+The C version is called `CDisjointUnion`.  A benchmark suggests that a long sequence of `unite` operations is about 3 times as fast
+with `CDisjointUnion` as with `DisjointUnion`.
 
 The implementation uses the remarkable Convenient Containers library from Jackson Allan.[[Allan]](#references).
 
@@ -145,16 +207,21 @@ The implementation uses the remarkable Convenient Containers library from Jackso
 `CSegmentTreeTemplate` is the C implementation of the generic class. Concrete classes are built on top of this in Ruby, just as with
 the pure Ruby `SegmentTreeTemplate` class.
 
-A benchmark suggests that a long sequence of `max_on` operations against a max-val Segment Tree is about 4 times as fast with the C
-version as with the Ruby version. I'm a bit suprised the improvment isn't larger, but we must remember that the C code must still
-interact with the Ruby objects in the underlying data array, and must "combine" them, etc., by calling Ruby lambdas.
+A benchmark suggests that a long sequence of `max_on` operations against a max-val Segment Tree is about 4 times as fast with C as
+with Ruby. I'm a bit suprised the improvment isn't larger, but remember that the C code must still interact with the Ruby objects in
+the underlying data array, and must combine them, etc., via Ruby lambdas.
 
 # References
-- [Allan] Allan, J., _CC: Convenient Containers_, https://github.com/JacksonAllan/CC, retrieved 2023-02-01.
-- [TvL1984] Tarjan, Robert E., van Leeuwen, J., _Worst-case Analysis of Set Union Algorithms_, Journal of the ACM, v31:2 (1984), pp 245–281.
-- [EEK2017] Edelkamp, S., Elmasry, A., Katajainen, J., _Optimizing Binary Heaps_, Theory Comput Syst (2017), vol 61, pp 606-636, DOI 10.1007/s00224-017-9760-2.
-- [McC1985] McCreight, E. M., _Priority Search Trees_, SIAM J. Comput., 14(2):257-276, 1985.
-- [DMNS2011] De, M., Maheshwari, A., Nandy, S. C., Smid, M., _An In-Place Priority Search Tree_, 23rd Canadian Conference on Computational Geometry, 2011.
-- [DMNS2013] De, M., Maheshwari, A., Nandy, S. C., Smid, M., _An In-Place Min-max Priority Search Tree_, Computational Geometry, v46 (2013), pp 310-327.
+- [Allan] Allan, J., _CC: Convenient Containers_, https://github.com/JacksonAllan/CC, (retrieved 2023-02-01).
+- [TvL1984] Tarjan, Robert E., van Leeuwen, J., _Worst-case Analysis of Set Union Algorithms_, Journal of the ACM, v31:2 (1984), pp
+  245–281, https://dl.acm.org/doi/10.1145/62.2160 (retrieved 2022-02-01).
+- [EEK2017] Edelkamp, S., Elmasry, A., Katajainen, J., _Optimizing Binary Heaps_, Theory Comput Syst (2017), vol 61, pp 606-636, DOI
+  10.1007/s00224-017-9760-2, https://kclpure.kcl.ac.uk/portal/files/87388857/TheoryComputingSzstems.pdf (retrieved 2022-02-02).
+- [McC1985] McCreight, E. M., _Priority Search Trees_, SIAM J. Comput., 14(2):257-276, 1985,
+  http://www.cs.duke.edu/courses/fall08/cps234/handouts/SMJ000257.pdf (retrieved 2023-02-02).
+- [DMNS2011] De, M., Maheshwari, A., Nandy, S. C., Smid, M., _An In-Place Priority Search Tree_, 23rd Canadian Conference on
+  Computational Geometry, 2011, http://www.cs.carleton.ca/~michiel/inplace_pst.pdf (retrieved 2023-02-02).
+- [DMNS2013] De, M., Maheshwari, A., Nandy, S. C., Smid, M., _An In-Place Min-max Priority Search Tree_, Computational Geometry, v46
+  (2013), pp 310-327, https://people.scs.carleton.ca/~michiel/MinMaxPST.pdf (retrieved 2023-02-02).
 
 [^minmaxpst]: See the comments in the fragmentary class `MinMaxPrioritySearchTree` for further details.

data/ext/c_segment_tree_template/segment_tree_template.c

@@ -353,7 +353,8 @@ static VALUE segment_tree_update_at(VALUE self, VALUE idx) {
  * (see SegmentTreeTemplate)
  */
 void Init_c_segment_tree_template() {
-  VALUE cSegmentTreeTemplate = rb_define_class_under(mDataStructuresRMolinari, "CSegmentTreeTemplate", rb_cObject);
+  VALUE mSegmentTree = rb_define_module_under(mDataStructuresRMolinari, "SegmentTree");
+  VALUE cSegmentTreeTemplate = rb_define_class_under(mSegmentTree, "CSegmentTreeTemplate", rb_cObject);
 
   rb_define_alloc_func(cSegmentTreeTemplate, segment_tree_alloc);
   rb_define_method(cSegmentTreeTemplate, "c_initialize", segment_tree_init, 4);

data/lib/data_structures_rmolinari/algorithms.rb

@@ -1,4 +1,4 @@
-# A collection of algorithms that use the module's data structures but don't belong as a method on one of the data structures
+# Algorithms that use the module's data structures but don't belong as a method on one of the data structures
 module DataStructuresRMolinari::Algorithms
   include Shared
 
@@ -11,12 +11,12 @@ module DataStructuresRMolinari::Algorithms
   #
   # A _maximal empty rectangle_ (MER) for P is an empty rectangle for P not properly contained in any other.
   #
-  # We enumerate all maximal empty rectangles for P, yielding each as (left, right, bottom, top) to a block. The algorithm is due to
-  # De, M., Maheshwari, A., Nandy, S. C., Smid, M., _An In-Place Min-max Priority Search Tree_, Computational Geometry, v46 (2013),
-  # pp 310-327.
+  # We enumerate all maximal empty rectangles for P, yielding each as (left, right, bottom, top). The algorithm is due to De, M.,
+  # 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
-  # MaxPST below takes O(n log^2 n) time, but m = O(n^2) so we are still O(m log n) overall.)
+  # 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+.
   def self.maximal_empty_rectangles(points)

data/lib/data_structures_rmolinari/c_segment_tree_template_impl.rb

@@ -3,110 +3,13 @@ require 'must_be'
 require_relative 'shared'
 require_relative 'c_segment_tree_template'
 
-# The template of Segment Tree, which can be used for various interval-related purposes, like efficiently finding the sum (or min or
-# max) on a arbitrary subarray of a given array.
+# The underlying functionality of the Segment Tree data type, implemented in C as a Ruby extension.
 #
-# There is an excellent description of the data structure at https://cp-algorithms.com/data_structures/segment_tree.html. The
-# Wikipedia article (https://en.wikipedia.org/wiki/Segment_tree) appears to describe a different data structure which is sometimes
-# called an "interval tree."
-#
-# For more details (and some close-to-metal analysis of run time, especially for large datasets) see
-# https://en.algorithmica.org/hpc/data-structures/segment-trees/. In particular, this shows how to do a bottom-up implementation,
-# which is faster, at least for large datasets and cache-relevant compiled code. These issues don't really apply to code written in
-# Ruby.
-#
-# This is a generic implementation, intended to allow easy configuration for concrete instances. See the parameters to the
-# initializer and the definitions of concrete realisations like MaxValSegmentTree.
-#
-# We do O(n) work to build the internal data structure at initialization. Then we answer queries in O(log n) time.
+# See SegmentTreeTemplate for more information.
 class DataStructuresRMolinari::CSegmentTreeTemplate
-
-  # Construct a concrete instance of a Segment Tree. See details at the links above for the underlying concepts here.
-  # @param combine a lambda that takes two values and munges them into a combined value.
-  #   - For example, if we are calculating sums over subintervals, combine.call(a, b) = a + b, while if we are doing maxima we will
-  #     return max(a, b).
-  #   - Things get more complicated when we are calculating, say, the _index_ of the maximal value in a subinterval. Now it is not
-  #     enough simply to store that index at each tree node, because to combine the indices from two child nodes we need to know
-  #     both the index of the maximal element in each child node's interval, but also the maximal values themselves, so we know
-  #     which one "wins" for the parent node. This affects the sort of work we need to do when combining and the value provided by
-  #     the +single_cell_array_val+ lambda.
-  # @param single_cell_array_val a lambda that takes an index i and returns the value we need to store in the #build
-  #     operation for the subinterval i..i.
-  #     - This will often simply be the value data[i], but in some cases it will be something else. For example, when we are
-  #       calculating the index of the maximal value on each subinterval we need [i, data[i]] here.
-  #     - If +update_at+ is called later, this lambda must close over the underlying data in a way that captures the updated value.
-  # @param size the size of the underlying data array, used in certain internal arithmetic.
-  # @param identity the value to return when we are querying on an empty interval
-  #   - for sums, this will be zero; for maxima, this will be -Infinity, etc
+  # (see SegmentTreeTemplate::initialize)
   def initialize(combine:, single_cell_array_val:, size:, identity:)
     # having sorted out the keyword arguments, pass them more easily to the C layer.
     c_initialize(combine, single_cell_array_val, size, identity)
   end
 end
-
-# 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.
-#
-# C version
-#
-# TODO: share the definition with (non-C) MasValSegmentTree. The only difference is the class of the underlying segment tree
-# template.
-module DataStructuresRMolinari
-  class CMaxValSegmentTree
-    extend Forwardable
-
-    # Tell the tree that the value at idx has changed
-    def_delegator :@structure, :update_at
-
-    # @param data an object that contains values at integer indices based at 0, via +data[i]+.
-    #   - This will usually be an Array, but it could also be a hash or a proc.
-    def initialize(data)
-      @structure = CSegmentTreeTemplate.new(
-        combine:               ->(a, b) { [a, b].max },
-        single_cell_array_val: ->(i) { data[i] },
-        size:                  data.size,
-        identity:              -Shared::INFINITY
-      )
-    end
-
-    # The maximum value in A(i..j).
-    #
-    # The arguments must be integers in 0...(A.size)
-    # @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) answers questions of the form "what is the index of the maximal value in the
-  # subinterval A(i..j)?" in O(log n) time.
-  #
-  # C version
-  class CIndexOfMaxValSegmentTree
-    extend Forwardable
-
-    # Tell the tree that the value at idx has changed
-    def_delegator :@structure, :update_at
-
-    # @param (see MaxValSegmentTree#initialize)
-    def initialize(data)
-      @structure = CSegmentTreeTemplate.new(
-        combine:               ->(p1, p2) { p1[1] >= p2[1] ? p1 : p2 },
-        single_cell_array_val: ->(i) { [i, data[i]] },
-        size:                  data.size,
-        identity:              nil
-      )
-    end
-
-    # 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) 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)
-      @structure.query_on(i, j)&.first # discard the value part of the pair, which is a bookkeeping
-    end
-  end
-
-end

data/lib/data_structures_rmolinari/disjoint_union.rb

@@ -89,5 +89,7 @@ class DataStructuresRMolinari::DisjointUnion
     else
       @d[e] = f
     end
+
+    nil
   end
 end

data/lib/data_structures_rmolinari/segment_tree.rb

@@ -0,0 +1,126 @@
+require_relative 'shared'
+
+# A namespace to hold the various bits and bobs related to the SegmentTree implementation
+module DataStructuresRMolinari::SegmentTree
+end
+
+require_relative 'segment_tree_template'   # Ruby implementation of the generic API
+require_relative 'c_segment_tree_template' # C implementation of the generic API
+
+# Segment Tree: various concrete implementations
+#
+# There is an excellent description of the data structure at https://cp-algorithms.com/data_structures/segment_tree.html. The
+# Wikipedia article (https://en.wikipedia.org/wiki/Segment_tree) appears to describe a different data structure which is sometimes
+# called an "interval tree."
+#
+# For more details (and some close-to-metal analysis of run time, especially for large datasets) see
+# https://en.algorithmica.org/hpc/data-structures/segment-trees/. In particular, this shows how to do a bottom-up implementation,
+# which is faster, at least for large datasets and cache-relevant compiled code. These issues don't really apply to code written in
+# Ruby.
+#
+# Here we provide several concrete segment tree implementations built on top of the template (generic) versions. Each instance is
+# backed either by the pure Ruby SegmentTreeTemplate or its C-based sibling CSegmentTreeTemplate
+module DataStructuresRMolinari
+  module SegmentTree
+    # A convenience method to construct a Segment Tree that, for a given array A(0...size), answers questions of the kind given by
+    # operation, using the template written in lang
+    #
+    # - @param data: the array A.
+    #   - It must respond to +#size+ and to +#[]+ with non-negative integer arguments.
+    # - @param operation: a supported "style" of Segment Tree
+    #   - for now, must be one of these (but you can write your own concrete version)
+    #     - +:max+: implementing +max_on(i, j)+, returning the maximum value in A(i..j)
+    #     - +:index_of_max+: implementing +index_of_max_val_on(i, j)+, returning an index corresponding to the maximum value in
+    #       A(i..j).
+    # - @param lang: the language in which the underlying "template" is written
+    #   - +:c+ or +:ruby+
+    #   - the C version will run faster but for now may be buggier and harder to debug
+    module_function def construct(data, operation, lang)
+      operation.must_be_in [:max, :index_of_max]
+      lang.must_be_in [:ruby, :c]
+
+      klass = operation == :max ? MaxValSegmentTree : IndexOfMaxValSegmentTree
+      template = lang == :ruby ? SegmentTreeTemplate : CSegmentTreeTemplate
+
+      klass.new(template, data)
+    end
+
+    # 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
+
+      # Tell the tree that the value at idx has changed
+      def_delegator :@structure, :update_at
+
+      # @param template_klass the "template" class that provides the generic implementation of the Segment Tree functionality.
+      # @param data an object that contains values at integer indices based at 0, via +data[i]+.
+      #   - This will usually be an Array, but it could also be a hash or a proc.
+      def initialize(template_klass, data)
+        data.must_be_a Enumerable
+
+        @structure = template_klass.new(
+          combine:               ->(a, b) { [a, b].max },
+          single_cell_array_val: ->(i) { data[i] },
+          size:                  data.size,
+          identity:              -Shared::INFINITY
+        )
+      end
+
+      # The maximum value in A(i..j).
+      #
+      # The arguments must be integers in 0...(A.size)
+      # @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) 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
+
+      # Tell the tree that the value at idx has changed
+      def_delegator :@structure, :update_at
+
+      # @param (see MaxValSegmentTree#initialize)
+      def initialize(template_klass, data)
+        data.must_be_a Enumerable
+
+        @structure = template_klass.new(
+          combine:               ->(p1, p2) { p1[1] >= p2[1] ? p1 : p2 },
+          single_cell_array_val: ->(i) { [i, data[i]] },
+          size:                  data.size,
+          identity:              nil
+        )
+      end
+
+      # 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) 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)
+        @structure.query_on(i, j)&.first # discard the value part of the pair, which is a bookkeeping
+      end
+    end
+
+    # The underlying functionality of the Segment Tree data type, implemented in C as a Ruby extension.
+    #
+    # See SegmentTreeTemplate for more information.
+    #
+    # Implementation note
+    #
+    # The functionality is entirely written in C. But we write the constructor in Ruby because keyword arguments are difficult to
+    # parse on the C side.
+    class CSegmentTreeTemplate
+      # (see SegmentTreeTemplate::initialize)
+      def initialize(combine:, single_cell_array_val:, size:, identity:)
+        # having sorted out the keyword arguments, pass them more easily to the C layer.
+        c_initialize(combine, single_cell_array_val, size, identity)
+      end
+    end
+  end
+end

data/lib/data_structures_rmolinari/segment_tree_template.rb

@@ -1,7 +1,7 @@
 require_relative 'shared'
 
-# The template of Segment Tree, which can be used for various interval-related purposes, like efficiently finding the sum (or min or
-# max) on a arbitrary subarray of a given array.
+# A generic implementation of Segment Tree, which can be used for various interval-related purposes, like efficiently finding the
+# sum (or min or max) on a arbitrary subarray of a given array.
 #
 # There is an excellent description of the data structure at https://cp-algorithms.com/data_structures/segment_tree.html. The
 # Wikipedia article (https://en.wikipedia.org/wiki/Segment_tree) appears to describe a different data structure which is sometimes
@@ -16,7 +16,7 @@ require_relative 'shared'
 # initializer and the definitions of concrete realisations like MaxValSegmentTree.
 #
 # We do O(n) work to build the internal data structure at initialization. Then we answer queries in O(log n) time.
-class DataStructuresRMolinari::SegmentTreeTemplate
+class DataStructuresRMolinari::SegmentTree::SegmentTreeTemplate
   include Shared
   include Shared::BinaryTreeArithmetic
 

data/lib/data_structures_rmolinari.rb

@@ -14,77 +14,12 @@ require_relative 'data_structures_rmolinari/algorithms'
 require_relative 'data_structures_rmolinari/disjoint_union'
 require_relative 'data_structures_rmolinari/c_disjoint_union' # version as a C extension
 
-require_relative 'data_structures_rmolinari/segment_tree_template'
-require_relative 'data_structures_rmolinari/c_segment_tree_template_impl'
+require_relative 'data_structures_rmolinari/segment_tree'
 
 require_relative 'data_structures_rmolinari/heap'
 require_relative 'data_structures_rmolinari/max_priority_search_tree'
 require_relative 'data_structures_rmolinari/min_priority_search_tree'
 
 module DataStructuresRMolinari
-  ########################################
-  # Concrete instances of Segment Tree
-  #
-  # @todo consider moving these into generic_segment_tree.rb and renaming that file
-
-  # 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
-
-    # Tell the tree that the value at idx has changed
-    def_delegator :@structure, :update_at
-
-    # @param data an object that contains values at integer indices based at 0, via +data[i]+.
-    #   - This will usually be an Array, but it could also be a hash or a proc.
-    def initialize(data)
-      data.must_be_a Enumerable
-
-      @structure = SegmentTreeTemplate.new(
-        combine:               ->(a, b) { [a, b].max },
-        single_cell_array_val: ->(i) { data[i] },
-        size:                  data.size,
-        identity:              -Shared::INFINITY
-      )
-    end
-
-    # The maximum value in A(i..j).
-    #
-    # The arguments must be integers in 0...(A.size)
-    # @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) 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
-
-    # Tell the tree that the value at idx has changed
-    def_delegator :@structure, :update_at
-
-    # @param (see MaxValSegmentTree#initialize)
-    def initialize(data)
-      data.must_be_a Enumerable
-
-      @structure = SegmentTreeTemplate.new(
-        combine:               ->(p1, p2) { p1[1] >= p2[1] ? p1 : p2 },
-        single_cell_array_val: ->(i) { [i, data[i]] },
-        size:                  data.size,
-        identity:              nil
-      )
-    end
-
-    # 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) 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)
-      @structure.query_on(i, j)&.first # discard the value part of the pair, which is a bookkeeping
-    end
-  end
+  # Add things here if needed
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_structures_rmolinari
 version: !ruby/object:Gem::Version
-  version: 0.4.4
+  version: 0.5.0
 platform: ruby
 authors:
 - Rory Molinari
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-02 00:00:00.000000000 Z
+date: 2023-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: must_be
@@ -97,6 +97,7 @@ files:
 - lib/data_structures_rmolinari/heap.rb
 - lib/data_structures_rmolinari/max_priority_search_tree.rb
 - lib/data_structures_rmolinari/min_priority_search_tree.rb
+- lib/data_structures_rmolinari/segment_tree.rb
 - lib/data_structures_rmolinari/segment_tree_template.rb
 - lib/data_structures_rmolinari/shared.rb
 homepage: https://github.com/rmolinari/data_structures