data_structures_rmolinari 0.4.4 → 0.5.1

data/ext/shared.h

@@ -0,0 +1,33 @@
+#ifndef SHARED_H
+#define SHARED_H
+
+#include <stddef.h>
+#include "ruby.h"
+
+#define mShared rb_define_module("Shared")
+#define eSharedDataError rb_const_get(mShared, rb_intern_const("DataError"))
+#define eSharedInternalLogicError rb_const_get(mShared, rb_intern_const("InternalLogicError"))
+#define mDataStructuresRMolinari rb_define_module("DataStructuresRMolinari")
+
+//#define debug(...) printf(__VA_ARGS__)
+#define debug(...)
+
+/* What we might think of as vector[index]. It is assignable */
+#define lval(vector, index) (*get(vector, index))
+
+/*
+ * Binary tree arithmetic for an implicit tree in an array, 1-based.
+ *
+ * TODO: into shared header
+ */
+#define TREE_ROOT 1
+size_t midpoint(size_t left, size_t right);
+size_t left_child(size_t i);
+size_t right_child(size_t i);
+
+/*
+ * Check that a Ruby value is a non-negative Fixnum and convert it to a C unsigned long
+ */
+unsigned long checked_nonneg_fixnum(VALUE val);
+
+#endif

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.1
 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
@@ -89,7 +89,9 @@ files:
 - ext/c_disjoint_union/extconf.rb
 - ext/c_segment_tree_template/extconf.rb
 - ext/c_segment_tree_template/segment_tree_template.c
+- ext/cc.h
 - ext/shared.c
+- ext/shared.h
 - lib/data_structures_rmolinari.rb
 - lib/data_structures_rmolinari/algorithms.rb
 - lib/data_structures_rmolinari/c_segment_tree_template_impl.rb
@@ -97,6 +99,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