data_structures_rmolinari 0.4.4 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 943ac55678a074cc0da3667dccbb07ee7d203639233f53bd8587af7fd8cd062e
-  data.tar.gz: ad235e5f4714e699f1cf5f113dd4b3a356a194cced5a74b60e17c5e3a896e01b
+  metadata.gz: a41b03a0d46982d64fc1ec5648174df24c6c9b0593ff93354ad90fc65ff84e8e
+  data.tar.gz: 544aa69540c9cef54c4eb6402b260bafbbeddf7dc5e770bf428976c11161c58e
 SHA512:
-  metadata.gz: a68de76c88c67fadc42752610c695b1f0b8fd17f34db9c806291aeab4c933fe84c6523615deb4197e1c9fa6d36dce30987cc4e8896a2b0c1700b7e72b5bd2fff
-  data.tar.gz: 9063d89a98d599f27db2585bf383dbfb13e8f927abce64ac7eafb2edd70c490ddad1f1fc51e0f11c24adf29f28ab8c56548a6db264b15ace239c63b1a2ce5a01
+  metadata.gz: 19efca577bb0c3c9524cf09b6f63c0e06beab70bfd20d1dbafa5034009be9bcb965ac5b8cee0ba0a39ecdcb646c401a54b363852a4572613941f7a34da174593
+  data.tar.gz: 05606e9c142a9bcb69a9fd555586b0ad8fe76bf7572af3dd82003de673d78b671b9a5edf1e5d4a2e4c7d5c6d5e41bef2ed1679573600725b74a25d4f3665c6ee

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

@@ -9,23 +9,13 @@ as fast as possible.
 
 The code is available as a gem: https://rubygems.org/gems/data_structures_rmolinari.
 
+It is distributed under the MIT license.
+
 ## Usage
 
 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 +32,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 +70,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 +121,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 +151,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.
+#
+# Put :index_of_max in place of :map to get an instance that returns "an index of the maximum value
+# over this subinterval".
+#
+# To use the generic code 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 +195,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 +209,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);