lite-containers 0.0.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ab4551d5c45aa8900a6f1efc501a564eab1a4a010a1c7ecaa309965a0541c272
+  data.tar.gz: d6fd375ee6d2eb8b0a127cd14190e8bf3f2cf596f2ca1247107a6b951c0d98da
+SHA512:
+  metadata.gz: 35b991f983faff3278c9b86d02d77c1cb86cbd7b5b0ff9b2129aa3046d19c40322dc9134ac528b85676efafc4d490bf2b07364112cfa9f8a7d9aa366f3c08749
+  data.tar.gz: 600d9406293be9e0dae2680b8e7d25faa39ff4f54be3ef77c4f6fdfb1f3d45fb87ef583c2f08ac75c0800db1bc6e276a95f8d50448597cb19f5a63e96e544258

data/.gitignore

@@ -0,0 +1,5 @@
+.byebug_history
+.ruby-version
+*.gem
+.idea/*
+coverage/*

data/.rubocop.yml

@@ -0,0 +1,72 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Metrics/ClassLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Metrics/AbcSize:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Metrics/CyclomaticComplexity:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Naming/MethodParameterName:
+  Enabled: false
+
+Naming/VariableNumber:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Lint/ShadowingOuterLocalVariable:
+  Enabled: false
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: start_of_line
+
+RSpec/ContextWording:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/IndexedLet:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+Style/ArgumentsForwarding:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/HashSyntax:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+group :test do
+  gem 'byebug', '~> 11'
+  gem 'markly'
+  gem 'rspec', '~> 3'
+  gem 'rubocop'
+  gem 'rubocop-rspec'
+  gem 'rubycritic'
+  gem 'ruby-prof'
+  gem 'simplecov'
+end

data/Gemfile.lock

@@ -0,0 +1,127 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
+    ast (2.4.2)
+    axiom-types (0.1.1)
+      descendants_tracker (~> 0.0.4)
+      ice_nine (~> 0.11.0)
+      thread_safe (~> 0.3, >= 0.3.1)
+    byebug (11.1.3)
+    childprocess (5.1.0)
+      logger (~> 1.5)
+    coercible (1.0.0)
+      descendants_tracker (~> 0.0.1)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
+    diff-lcs (1.5.1)
+    docile (1.4.1)
+    erubi (1.13.1)
+    flay (2.13.3)
+      erubi (~> 1.10)
+      path_expander (~> 1.0)
+      ruby_parser (~> 3.0)
+      sexp_processor (~> 4.0)
+    flog (4.8.0)
+      path_expander (~> 1.0)
+      ruby_parser (~> 3.1, > 3.1.0)
+      sexp_processor (~> 4.8)
+    ice_nine (0.11.2)
+    json (2.9.1)
+    kwalify (0.7.2)
+    language_server-protocol (3.17.0.3)
+    launchy (3.0.1)
+      addressable (~> 2.8)
+      childprocess (~> 5.0)
+    logger (1.6.4)
+    markly (0.12.1)
+    parallel (1.26.3)
+    parser (3.2.2.4)
+      ast (~> 2.4.1)
+      racc
+    path_expander (1.1.3)
+    public_suffix (5.1.1)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    reek (6.1.4)
+      kwalify (~> 0.7.0)
+      parser (~> 3.2.0)
+      rainbow (>= 2.0, < 4.0)
+    regexp_parser (2.10.0)
+    rexml (3.4.0)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.2)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.2)
+    rubocop (1.59.0)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.2.2.4)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.30.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.30.0)
+      parser (>= 3.2.1.0)
+    rubocop-rspec (3.0.0)
+      rubocop (~> 1.40)
+    ruby-prof (1.6.3)
+    ruby-progressbar (1.13.0)
+    ruby_parser (3.21.1)
+      racc (~> 1.5)
+      sexp_processor (~> 4.16)
+    rubycritic (4.9.1)
+      flay (~> 2.13)
+      flog (~> 4.7)
+      launchy (>= 2.5.2)
+      parser (>= 3.2.2.4)
+      rainbow (~> 3.1.1)
+      reek (~> 6.0, < 6.2)
+      rexml
+      ruby_parser (~> 3.21)
+      simplecov (>= 0.22.0)
+      tty-which (~> 0.5.0)
+      virtus (~> 2.0)
+    sexp_processor (4.17.3)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.1)
+    simplecov_json_formatter (0.1.4)
+    thread_safe (0.3.6)
+    tty-which (0.5.0)
+    unicode-display_width (2.6.0)
+    virtus (2.0.0)
+      axiom-types (~> 0.1)
+      coercible (~> 1.0)
+      descendants_tracker (~> 0.0, >= 0.0.3)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  byebug (~> 11)
+  markly
+  rspec (~> 3)
+  rubocop
+  rubocop-rspec
+  ruby-prof
+  rubycritic
+  simplecov
+
+BUNDLED WITH
+   2.4.1

data/README.md

@@ -0,0 +1,145 @@
+# lite-containers
+
+A collection of containers implemented in pure Ruby. 
+
+- `Heap` uses the well-known heap algorithm. The heap contract 
+guarantees that the highest ranking element is always on top 
+- `SortedArray` uses built-in quick sort and binary search to 
+ keep elements ordered
+- `AvlTree` keeps elements in a self-balancing binary search tree
+
+## Common features
+All containers have the following in common:
+- `empty?` and `size` methods to query the size 
+(along with the synonyms: `length`, `count`)
+- the `drain!` method that empties the container and 
+returns all elements in descending order (top priority first).
+
+## Constructor parameters
+To keep elements sorted the containers need certain parameters
+and helpers provided by the client code.
+- First parameter to the constructor is always `type`, taking values
+of `min` and `max`, telling the container how to interpret priority.
+- `key_extractor` is a proc that receives an element and produces 
+the key used for sorting. When key extractor is `nil`, the 
+value itself is considered the sort key.
+- Sorted array and AVL tree can only operate on unique
+entries. Their constructors expect `merge` parameter 
+to supply a merge strategy. Allowed values are `:replace`, `:keep` 
+or a proc that performs the merge. The proc should take two elements 
+as parameters and return a single one. The default strategy 
+for both containers is `:replace` meaning that in presence of duplicates 
+the new element replaces the old one.
+
+Helpers must honor the following rules for the containers
+to maintain consistent sort order:
+- The key extractor must always return the same key for the same value
+- The new merged element must resolve to the same key
+as the original two.
+
+Containers do not enforce these rules; it is the responsibility 
+of the client code to provide correctly implemented helpers.
+
+## Heap
+Heap is the simplest of the three containers in this library. 
+It supports `push`/`<<` method that inserts an element, `top` to
+return the top priority element, and `pop` to remove the top priority
+element. 
+
+```ruby rspec heap
+require 'lite/containers/heap'
+
+heap = Lite::Containers::Heap.instance(:max)
+heap << 5 << 1 << 3
+
+expect(heap.top).to eq(5)
+expect(heap.pop).to eq(5)
+expect(heap.drain!).to eq([3, 1])
+```
+
+## Sorted array
+Useful for maintaining relatively stable lists that either never change 
+or change infrequently. Each insert or delete will reallocate 
+the underlying array making it really inefficient 
+when the churn is high.
+
+Depending on the nature of the data, different constructors 
+can be used to build the sorted array. If the
+data come in random order it is necessary to call `from_unsorted`
+to have the container sort them.
+If the data are already sorted, `from_sorted` could be used, 
+or even `from_sorted_unsafe`. The former checks whether the data 
+are properly sorted and raises an error when it discovers 
+unexpected ordering. The second one performs no check on 
+the data leaving that responsibility to the client code.
+
+Sorted array includes the `Enumerable` module, giving
+access to all its methods like `map`, `reduce` etc.
+
+
+```ruby rspec sorted_array
+require 'lite/containers/sorted_array'
+
+sorted_array = Lite::Containers::SortedArray.from_unsorted(
+  :max,
+  [{ income: 0, tax: 15 }, { income: 120_000, tax: 25 }, { income: 60_000, tax: 20 }],
+  key_extractor: proc { |elem| elem[:income] }
+)
+
+expect(sorted_array.front).to eq({ income: 120_000, tax: 25 })
+expect(sorted_array.back).to eq({ income: 0, tax: 15 })
+expect(sorted_array.find(60_000)).to eq({ income: 60_000, tax: 20 })
+expect(sorted_array.find_or_nearest_forwards(80_000)).to eq({ income: 120_000, tax: 25 })
+expect(sorted_array.find_or_nearest_backwards(80_000)).to eq({ income: 60_000, tax: 20 })
+```
+
+## AVL tree
+Comes in two flavors – `ImplicitKey` and `ExplicitKey`.
+
+- `ImplicitKey` implements `push`/`<<` with single parameter – the element. 
+It may need a *key extractor* to be supplied.
+
+```ruby rspec avl_tree_implicit
+require 'lite/containers/avl_tree'
+
+tree = Lite::Containers::AvlTree::ImplicitKey.instance(
+  :max,
+  key_extractor: proc { |elem| elem[:time] }
+)
+
+tree << { time: 0, t: 30 } << { time: 45, t: 600 } << { time: 60, t: 800 } << { time: 120, t: 750 }
+
+expect(tree.front).to eq({ time: 120, t: 750 })
+expect(tree.back).to eq({ time: 0, t: 30 })
+expect(tree.find(45)).to eq({ time: 45, t: 600 })
+expect(tree.find_or_nearest_forwards(55)).to eq({ time: 60, t: 800 })
+expect(tree.find_or_nearest_backwards(55)).to eq({ time: 45, t: 600 })
+```
+
+- `ExplicitKey` implements `insert` that takes two parameters – the key and the value.
+Methods like `front`, `back`, `find` etc. return a key/value tuple instead 
+of a single element.
+
+```ruby rspec avl_tree_explicit
+require 'lite/containers/avl_tree'
+
+tree = Lite::Containers::AvlTree::ExplicitKey.instance(
+  :min,
+  merge: proc { |old, fresh| { count: old[:count] + fresh[:count] } }
+)
+
+tree.insert(0, { count: 1 })
+    .insert(10, { count: 1 })
+    .insert(10, { count: 1 })
+    .insert(20, { count: 1 })
+    .insert(30, { count: 1 })
+
+expect(tree.pop_front).to eq([0, { count: 1 }])
+expect(tree.pop_back).to eq([30, { count: 1 }])
+expect(tree.drain!).to eq([[10, { count: 2 }], [20, { count: 1 }]])
+```
+
+AVL tree also includes the `Enumerable` module.
+
+## License
+This library is published under MIT license

data/bench/containers_bench.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'benchmark'
+require_relative '../lib/lite/containers/sorted_array'
+require_relative '../lib/lite/containers/heap'
+require_relative '../lib/lite/containers/avl_tree'
+
+module Lite
+  module Containers
+    module AbstractBench
+      def measure(n)
+        warm_up
+        subjects = populate(n)
+        output_to_sorted_array(subjects)
+      end
+
+      def warm_up
+        puts '  warm up ...'
+
+        100.times do
+          subject = initial_subject
+          1000.times do
+            insert_single(subject, rand(1000))
+            output(subject)
+          end
+        end
+      end
+
+      def populate(n)
+        puts "\n  populate ..."
+
+        subjects = []
+        times = 100_000 / n
+
+        result = Benchmark.measure do
+          times.times do
+            subject = initial_subject
+            n.times do
+              insert_single(subject, rand(n))
+            end
+            subjects << subject
+          end
+        end
+        puts result
+        subjects
+      end
+
+      def output_to_sorted_array(subjects)
+        puts "\n  output from #{subjects.length} subjects to sorted array of #{subjects.first&.length || 0}"
+
+        result = Benchmark.measure do
+          subjects.each do |subject|
+            output(subject)
+          end
+        end
+        puts result
+      end
+    end
+
+    module ArrayBench
+      extend AbstractBench
+
+      def self.initial_subject
+        SortedArray.from_sorted_unsafe(:max, [])
+      end
+
+      def self.insert_single(array, value)
+        array << value
+      end
+
+      def self.output(array)
+        array.to_array
+      end
+    end
+
+    module HeapBench
+      extend AbstractBench
+
+      def self.initial_subject
+        Heap.instance(:max)
+      end
+
+      def self.insert_single(heap, value)
+        heap << value
+      end
+
+      def self.output(heap)
+        heap.drain!
+      end
+    end
+
+    module AvlTreeBench
+      extend AbstractBench
+
+      def self.initial_subject
+        AvlTree::ExplicitKey.instance :max
+      end
+
+      def self.insert_single(tree, value)
+        tree.insert(value, nil)
+      end
+
+      def self.output(tree)
+        tree.traverse.to_a
+      end
+    end
+  end
+end
+
+N = 10_000
+
+puts "------------- ARRAY #{N} -------------"
+Lite::Containers::ArrayBench.measure(N)
+puts '--------------------------------------'
+puts "------------- HEAP #{N} --------------"
+Lite::Containers::HeapBench.measure(N)
+puts '--------------------------------------'
+puts "------------- AVL #{N} ---------------"
+Lite::Containers::AvlTreeBench.measure(N)
+puts '--------------------------------------'
+
+# https://stackoverflow.com/questions/6531543/efficient-implementation-of-binary-heaps

data/lib/lite/containers/abstract/collection.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lite
+  module Containers
+    module Abstract
+      module Collection
+        def size
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+
+        def length
+          size
+        end
+
+        def count
+          size
+        end
+
+        def empty?
+          size.zero?
+        end
+      end
+    end
+  end
+end

data/lib/lite/containers/abstract/deque.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'queue'
+
+module Lite
+  module Containers
+    module Abstract
+      module Deque
+        include Queue
+
+        # Removes and returns lowest priority element. Does nothing if empty
+        def back
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+
+        # Removes and returns lowest priority element. Does nothing if empty
+        def pop_back
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+      end
+    end
+  end
+end

data/lib/lite/containers/abstract/implicit_key.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'queue'
+
+module Lite
+  module Containers
+    module Abstract
+      module ImplicitKey
+        # Inserts element at its corresponding place.
+        # In case element is already there applies merge strategy
+        def push(_element)
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+
+        # Inserts element the way push does. Returns self
+        def <<(element)
+          push(element)
+          self
+        end
+      end
+    end
+  end
+end

data/lib/lite/containers/abstract/queue.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Lite
+  module Containers
+    module Abstract
+      module Queue
+        # Returns highest priority element or nil if empty
+        def front
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+
+        # Removes and returns highest priority element or nil if empty
+        def pop_front
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+
+        # Returns all elements in descending order by priority
+        def drain!
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+      end
+    end
+  end
+end

data/lib/lite/containers/abstract/sorted_map.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Lite
+  module Containers
+    module Abstract
+      module SortedMap
+        # Returns if key exists, false otherwise
+        def key?(key)
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+
+        # Returns element under given key if exists
+        def find(_key)
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+
+        # Returns element under given key or nearest element under lower priority key if exists
+        def find_or_nearest_backwards(_key)
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+
+        # Returns value under given key or nearest element under higher priority key if exists
+        def find_or_nearest_forwards(_key)
+          raise NotImplementedError, "#{self.class.name}##{__method__} unimplemented"
+        end
+      end
+    end
+  end
+end

data/lib/lite/containers/avl_tree/balance.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Lite
+  module Containers
+    class AvlTree
+      module Balance
+        def rebalance(node) # rubocop:disable Metrics/AbcSize
+          case balance_factor(node)
+          when -2
+            if height(node.left.right) > height(node.left.left)
+              rotate_left_right(node)
+            else
+              rotate_right(node)
+            end
+          when 2
+            if height(node.right.left) > height(node.right.right)
+              rotate_right_left(node)
+            else
+              rotate_left(node)
+            end
+          else
+            update_height(node)
+            node
+          end
+        end
+
+        def rotate_left(node)
+          right = node.right
+          node.right = right.left
+          right.left = node
+          update_height node
+          update_height right
+          right
+        end
+
+        def rotate_right(node)
+          left = node.left
+          node.left = left.right
+          left.right = node
+          update_height node
+          update_height left
+          left
+        end
+
+        def rotate_right_left(node)
+          node.right = rotate_right(node.right)
+          rotate_left(node)
+        end
+
+        def rotate_left_right(node)
+          node.left = rotate_left(node.left)
+          rotate_right(node)
+        end
+
+        def update_height(node)
+          left_height = height(node.left)
+          right_height = height(node.right)
+          # rubocop:disable Style/MinMaxComparison
+          max = left_height > right_height ? left_height : right_height
+          # rubocop:enable Style/MinMaxComparison
+          node.height = max + 1
+        end
+
+        def balance_factor(node)
+          height(node.right) - height(node.left)
+        end
+
+        def height(node)
+          node&.height || 0
+        end
+      end
+    end
+  end
+end