data_structures_rmolinari 0.5.6 → 0.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fbafd7af3c7bd2d1eee3303fd8b8a759b0d67fc29bfdca3b7f67b626e9fe175
-  data.tar.gz: 5a870554e38c61b1e1af64d2205bc002cf7cb731e5412606543ffdce014342b4
+  metadata.gz: da4fc2b27a4f5c1071af7965dac6d3363cbfcb350f1ff391e88e6f7145561822
+  data.tar.gz: 114c9f4fb025ded31a2a42832aa7376333be03e58fe72e94ff3a1822a0e433d3
 SHA512:
-  metadata.gz: fcdaae719324c5b8b7914eb6a982563d58ee10170d52280c58429e8d9b5a7e5224079350ab15ad618b5cacbcdf340c17feec2b34616e17847d5b0e16a7569d50
-  data.tar.gz: 446e2190ff33f65c9cb6cedd6043af506aa6f395f279e54520b2ba1c0c04fbd8504615f1a94e09232edefee9b0cb0d55363aa20b6504467d70f6766b19698464
+  metadata.gz: f13b0ab86555fcb9d0cef6bdb788c20a4335ad2e08e17e2a58993bffa2bc0eec8beb7299af4a61ec6c033931534c14dd270cb157640c5402ddb7e6a1fa676156
+  data.tar.gz: b620688430c178d7e865b1cafd7b1628f0a9fb37bbb5aaba8879ab8b5f9563fa27f8c7c4368516940ede905a5bef5b02f3fb2c3e0263845d4103c6cb14492a5f

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [0.5.8] 2025-12-08
+
+- Algorithms
+  - #first_k: the smallest k elements of an enumerable, using a Heap internally
+
+## [0.5.7] 2024-01-04
+
+- Heap
+  - addd top_priority method
+
 ## [0.5.6] 2024-01-04
 
 - Heap

data/README.md

@@ -53,12 +53,13 @@ operations:
 
 - `insert(item, priority)`, insert the given item with the stated priority.
   - By default, items must be distinct.
-- `top`, returning the element with smallest priority
+- `top`, return the element with smallest priority
+- `top_priority`, return the _priority_ of the top element
 - `pop`, return the element with smallest priority and remove it from the structure
 - `update(item, priority)`, update the priority of the given item, which must already be in the heap
-- `update_by_delta(item, delta)`, update the priorityof the given item by adding delta to the priority; the item must already be in the heap
+- `update_by_delta(item, delta)`, update the priority of the given item by adding delta to the priority; the item must already be in the heap
 
-`top` is O(1). The others are O(log n) where n is the number of items in the heap.
+`top` and `top_priority` are O(1). The others are O(log n) where n is the number of items in the heap.
 
 By default we have a min-heap: the top element is the one with smallest priority. A configuration parameter at construction can make
 it a max-heap.
@@ -122,7 +123,7 @@ 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
@@ -160,7 +161,7 @@ initializer. Figuring out the details requires some knowledge of the internal me
 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`
+Since there are several concrete "types" and two underlying generic implementations there is a convenience method on the `SegmentTree`
 module to get instances.
 
 ``` ruby
@@ -172,7 +173,7 @@ 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
+# Put :index_of_max in place of :max 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.
@@ -194,6 +195,10 @@ The Algorithms submodule contains some algorithms using the data structures.
     [left, right, bottom, top].
   - The algorithm is due to [[DMNS2013]](#references).
 
+- `first_k(enumerable, k)
+  - Given an enumerable, return the first k elements in sorted order.  That is, return the first k (smallest) elements of the sorted
+    version of the enumerable. We use a heap.  Run time is O(n log k), where n is the size of the enumerable.
+
 # C Extensions
 
 As another learning process I have implemented several of these data structures as C extensions. The APIs are the same.
@@ -217,7 +222,7 @@ I'm a bit suprised the improvement isn't larger, but remember that the C code mu
 in the underlying data array, and must access and combine them via Ruby lambdas.
 
 # References
-- [Allan] Allan, J., _CC: Convenient Containers_, https://github.com/JacksonAllan/CC, (retrieved 2023-02-01).
+- [Allan] Allan, J., _CC: Convenient Containers_, https://github.com/JacksonAllan/CC, (retrieved 2024-12-04).
 - [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