pairing_heap 0.3.0 → 2.0.0

data/Rakefile

@@ -2,6 +2,7 @@
 
 require "bundler/gem_tasks"
 require "rake/testtask"
+require "standard/rake"
 
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
@@ -9,4 +10,4 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList["test/**/*_test.rb"]
 end
 
-task default: %i[test]
+task default: %i[test standard]

data/lib/pairing_heap/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PairingHeap
-  VERSION = "0.3.0"
+  VERSION = "2.0.0"
 end

data/lib/pairing_heap.rb

@@ -8,18 +8,21 @@ module PairingHeap
       return heaps if heaps.next_sibling.nil?
 
       # [H1, H2, H3, H4, H5, H6, H7] => [H1H2, H3H4, H5H6, H7]
-      stack = []
-      current = heaps
-      while current
-        prev = current
-        current = current.next_sibling
-        unless current
-          stack << prev
+      pairs = nil
+      left = heaps
+      while left
+        right = left.next_sibling
+        unless right
+          left.next_sibling = pairs
+          pairs = left
           break
         end
-        next_val = current.next_sibling
-        stack << meld(prev, current)
-        current = next_val
+        next_val = right.next_sibling
+        right = meld(left, right)
+        right.next_sibling = pairs
+        pairs = right
+
+        left = next_val
       end
 
       # [H1H2, H3H4, H5H6, H7]
@@ -27,13 +30,14 @@ module PairingHeap
       # [H1H2, H3H45H67]
       # [H1H2H3H45H67]
       # return H1H2H3H45H67
-      while true
-        right = stack.pop
-        return right if stack.empty?
-
-        left = stack.pop
-        stack << meld(left, right)
+      left = pairs
+      right = pairs.next_sibling
+      while right
+        next_val = right.next_sibling
+        left = meld(left, right)
+        right = next_val
       end
+      left
     end
   end
   private_constant :MergePairs
@@ -43,22 +47,22 @@ module PairingHeap
   class PairingHeap
     class Node
       attr_accessor :elem, :priority, :subheaps, :parent, :prev_sibling, :next_sibling
-      def initialize(elem, priority, subheaps, parent, prev_sibling, next_sibling)
+      def initialize(elem, priority)
         @elem = elem
         @priority = priority
-        @subheaps = subheaps
-        @parent = parent
-        @prev_sibling = prev_sibling
-        @next_sibling = next_sibling
+        @subheaps = nil
+        @parent = nil
+        @prev_sibling = nil
+        @next_sibling = nil
       end
 
       def remove_from_parents_list!
-        if self.prev_sibling
-          self.prev_sibling.next_sibling = self.next_sibling
-          self.next_sibling.prev_sibling = self.prev_sibling if self.next_sibling
-        elsif self.parent.subheaps.equal?(self)
-          self.parent.subheaps = self.next_sibling
-          self.next_sibling.prev_sibling = nil if self.next_sibling
+        if prev_sibling
+          prev_sibling.next_sibling = next_sibling
+          next_sibling.prev_sibling = prev_sibling if next_sibling
+        else # parent.subheaps must equal self
+          parent.subheaps = next_sibling
+          next_sibling.prev_sibling = nil if next_sibling
         end
         self.prev_sibling = nil
         self.next_sibling = nil
@@ -66,7 +70,8 @@ module PairingHeap
     end
     private_constant :Node
 
-    # @param &block Optional heap property priority comparator. `<:=.to_proc` by default
+    # @yield [l_priority, r_priority] Optional heap property priority comparator. `<:=.to_proc` by default
+    # @yieldreturn [boolean] if `l_priority` is more prioritary than `r_priority`, or the priorities are equal
     def initialize(&block)
       @root = nil
       @nodes = {}
@@ -79,15 +84,20 @@ module PairingHeap
     # @param priority Priority of the element
     # @raise [ArgumentError] if the element is already in the heap
     # @return [PairingHeap]
-    def push(elem, priority)
+    def push(elem, priority = elem)
       raise ArgumentError, "Element already in the heap" if @nodes.key?(elem)
 
-      node = Node.new(elem, priority, nil, nil, nil, nil)
+      node = Node.new(elem, priority)
       @nodes[elem] = node
-      @root = meld(@root, node)
+      @root = if @root
+        meld(@root, node)
+      else
+        node
+      end
       self
     end
-    alias enqueue push
+    alias_method :enqueue, :push
+    alias_method :offer, :push
 
     # Returns the element at the top of the heap
     #   Time Complexity: O(1)
@@ -95,7 +105,13 @@ module PairingHeap
       @root&.elem
     end
 
+    # @return [Object]
     def peek_priority
+      @root&.priority
+    end
+
+    # @return [Array(Object, Object)]
+    def peek_with_priority
       [@root&.elem, @root&.priority]
     end
 
@@ -116,13 +132,12 @@ module PairingHeap
     def size
       @nodes.size
     end
-    alias length size
+    alias_method :length, :size
 
-    # Removes element from the top of the heap
+    # Removes element from the top of the heap and returns it
     #   Time Complexity: O(N)
     #   Amortized time Complexity: O(log(N))
-    # @raise [ArgumEntError] if the heap is empty
-    # @return [PairingHeap]
+    # @raise [ArgumentError] if the heap is empty
     def pop
       raise ArgumentError, "Cannot remove from an empty heap" if @root.nil?
 
@@ -136,9 +151,17 @@ module PairingHeap
       end
       elem
     end
-    alias dequeue pop
+    alias_method :dequeue, :pop
 
+    # @return [Object]
     def pop_priority
+      node = @root
+      pop
+      node.priority
+    end
+
+    # @return [Array(Object, Object)]
+    def pop_with_priority
       node = @root
       pop
       [node.elem, node.priority]
@@ -149,7 +172,7 @@ module PairingHeap
     #   Amortized Time Complexity: o(log(N))
     # @param elem Element
     # @param priority New priority
-    # @raise [ArgumentError] if the element heap is not in heap or the new priority is less prioritary
+    # @raise [ArgumentError] if the element is not in the heap or the new priority is less prioritary
     # @return [PairingHeap]
     def change_priority(elem, priority)
       node = @nodes[elem]
@@ -171,7 +194,7 @@ module PairingHeap
     # Removes element from the heap
     #   Time Complexity: O(N)
     #   Amortized Time Complexity: O(log(N))
-    # @raise [ArgumentError] if the element heap is not in heap
+    # @raise [ArgumentError] if the element is not in the heap
     # @return [PairingHeap]
     def delete(elem)
       node = @nodes[elem]
@@ -180,26 +203,57 @@ module PairingHeap
       @nodes.delete(elem)
       if node.parent.nil?
         @root = merge_pairs(node.subheaps)
+        if @root
+          @root.parent = nil
+          @root.prev_sibling = nil
+          @root.next_sibling = nil
+        end
       else
         node.remove_from_parents_list!
         new_heap = merge_pairs(node.subheaps)
         if new_heap
-          new_heap.prev_sibling = nil
-          new_heap.next_sibling = nil
+          @root = meld(new_heap, @root)
+          @root.parent = nil
+          @root.prev_sibling = nil
+          @root.next_sibling = nil
         end
-        @root = meld(new_heap, @root)
       end
-      @root&.parent = nil
       self
     end
 
+    # Returns priority of the provided element
+    #   Time Complexity: O(1)
+    # @raise [ArgumentError] if the element is not in the heap
+    # @return [Object]
+    def get_priority(elem)
+      node = @nodes[elem]
+      raise ArgumentError, "Provided element is not in heap" if node.nil?
+      node.priority
+    end
+
+    # Returns a pair where first element is success flag, and second element is priority
+    #   Time Complexity: O(1)
+    # @return [Array(false, nil)] if the element is not in heap
+    # @return [Array(true, Object)] if the element is in heap;
+    #  second element of returned tuple is the priority
+    def get_priority_if_exists(elem)
+      node = @nodes[elem]
+      return [false, nil] if node.nil?
+      [true, node.priority]
+    end
+
+    # Returns enumerator of elements. No order guarantees are provided.
+    # @return [Enumerator]
+    def each
+      return to_enum(__method__) { size } unless block_given?
+      NodeVisitor.visit_node(@root) { |x| yield x.elem }
+    end
+
     private
+
     include MergePairs
 
     def meld(left, right)
-      return right if left.nil?
-      return left if right.nil?
-
       if @order[left.priority, right.priority]
         parent = left
         child = right
@@ -219,16 +273,17 @@ module PairingHeap
   class SimplePairingHeap
     class Node
       attr_accessor :elem, :priority, :subheaps, :next_sibling
-      def initialize(elem, priority, subheaps, next_sibling)
+      def initialize(elem, priority)
         @elem = elem
         @priority = priority
-        @subheaps = subheaps
-        @next_sibling = next_sibling
+        @subheaps = nil
+        @next_sibling = nil
       end
     end
     private_constant :Node
 
-    # @param &block Optional heap property priority comparator. `<:=.to_proc` by default
+    # @yield [l_priority, r_priority] Optional heap property priority comparator. `<:=.to_proc` by default
+    # @yieldreturn [boolean] if `l_priority` is more prioritary than `r_priority`, or the priorities are equal
     def initialize(&block)
       @root = nil
       @order = block || :<=.to_proc
@@ -239,15 +294,19 @@ module PairingHeap
     #   Time Complexity: O(1)
     # @param elem Element to be pushed
     # @param priority Priority of the element
-    # @raise [ArgumentError] if the element is already in the heap
     # @return [PairingHeap]
-    def push(elem, priority)
-      node = Node.new(elem, priority, nil, nil)
-      @root = meld(@root, node)
+    def push(elem, priority = elem)
+      node = Node.new(elem, priority)
+      @root = if @root
+        meld(@root, node)
+      else
+        node
+      end
       @size += 1
       self
     end
-    alias enqueue push
+    alias_method :enqueue, :push
+    alias_method :offer, :push
 
     # Returns the element at the top of the heap
     #   Time Complexity: O(1)
@@ -255,7 +314,13 @@ module PairingHeap
       @root&.elem
     end
 
+    # @return [Object]
     def peek_priority
+      @root&.priority
+    end
+
+    # @return [Array(Object, Object)]
+    def peek_with_priority
       [@root&.elem, @root&.priority]
     end
 
@@ -273,42 +338,51 @@ module PairingHeap
 
     # Time Complexity: O(1)
     # @return [Integer]
-    def size
-      @size
-    end
-    alias length size
+    attr_reader :size
+    alias_method :length, :size
 
-    # Removes element from the top of the heap
+    # Removes an element from the top of the heap and returns it
     #   Time Complexity: O(N)
     #   Amortized time Complexity: O(log(N))
-    # @raise [ArgumEntError] if the heap is empty
-    # @return [PairingHeap]
+    # @raise [ArgumentError] if the heap is empty
     def pop
       raise ArgumentError, "Cannot remove from an empty heap" if @root.nil?
       @size -= 1
 
       elem = @root.elem
       @root = merge_pairs(@root.subheaps)
-      if @root
-        @root.next_sibling = nil
-      end
+      @root&.next_sibling = nil
+
       elem
     end
-    alias dequeue pop
+    alias_method :dequeue, :pop
 
+    # @return [Object]
     def pop_priority
+      node = @root
+      pop
+      node.priority
+    end
+
+    # @return [Array(Object, Object)]
+    def pop_with_priority
       node = @root
       pop
       [node.elem, node.priority]
     end
 
+    # Returns enumerator of elements. No order guarantees are provided.
+    # @return [Enumerator]
+    def each
+      return to_enum(__method__) { size } unless block_given?
+      NodeVisitor.visit_node(@root) { |x| yield x.elem }
+    end
+
     private
+
     include MergePairs
 
     def meld(left, right)
-      return right if left.nil?
-      return left if right.nil?
-
       if @order[left.priority, right.priority]
         parent = left
         child = right
@@ -322,16 +396,15 @@ module PairingHeap
     end
   end
 
-
   # Priority queue where the smallest priority is the most prioritary
   class MinPriorityQueue < PairingHeap
     def initialize
       super(&:<=)
     end
 
-    alias decrease_key change_priority
-    alias min peek
-    alias extract_min dequeue
+    alias_method :decrease_key, :change_priority
+    alias_method :min, :peek
+    alias_method :extract_min, :dequeue
   end
 
   # Priority queue where the highest priority is the most prioritary
@@ -340,17 +413,17 @@ module PairingHeap
       super(&:>=)
     end
 
-    alias increase_key change_priority
-    alias max peek
-    alias extract_max dequeue
+    alias_method :increase_key, :change_priority
+    alias_method :max, :peek
+    alias_method :extract_max, :dequeue
   end
 
   # Priority queue with change_priority, that accepts changing to a less prioritary priority
   class SafeChangePriorityQueue < PairingHeap
-    # Changes a priority of the element to a more prioritary one
+    # Changes a priority of the element
     #   Time Complexity: O(N)
     #   Amortized Time Complexity: O(log(N))
-    # @raise [ArgumentError] if the element heap is not in the heap
+    # @raise [ArgumentError] if the element is not in the heap
     # @return [PairingHeap]
     def change_priority(elem, priority)
       raise ArgumentError, "Provided element is not in heap" unless @nodes.key?(elem)
@@ -362,4 +435,22 @@ module PairingHeap
       end
     end
   end
+
+  module NodeVisitor
+    extend self
+
+    def visit_node(node, &block)
+      return unless node
+
+      block.call(node)
+
+      if node.subheaps
+        visit_node(node.subheaps, &block)
+      end
+      if node.next_sibling
+        visit_node(node.next_sibling, &block)
+      end
+    end
+  end
+  private_constant :NodeVisitor
 end

data/pairing_heap.gemspec

@@ -3,19 +3,19 @@
 require_relative "lib/pairing_heap/version"
 
 Gem::Specification.new do |spec|
-  spec.name          = "pairing_heap"
-  spec.version       = PairingHeap::VERSION
-  spec.authors       = ["Marcin Henryk Bartkowiak"]
-  spec.email         = ["mhbartkowiak@gmail.com"]
-
-  spec.summary       = "Performant priority queue in pure ruby with support for changing priority"
-  spec.description   = "Performant priority queue in pure ruby with support for changing priority using pairing heap data structure"
-  spec.homepage      = "https://github.com/mhib/pairing_heap"
-  spec.license       = "MIT"
+  spec.name = "pairing_heap"
+  spec.version = PairingHeap::VERSION
+  spec.authors = ["Marcin Henryk Bartkowiak"]
+  spec.email = ["mhbartkowiak@gmail.com"]
+
+  spec.summary = "Performant priority queue in pure ruby with support for changing priority"
+  spec.description = "Performant priority queue in pure ruby with support for changing priority using pairing heap data structure"
+  spec.homepage = "https://github.com/mhib/pairing_heap"
+  spec.license = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
 
-  spec.metadata["homepage_uri"]      = spec.homepage
-  spec.metadata["source_code_uri"]   = spec.homepage
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
   spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/pairing_heap"
 
   # Specify which files should be added to the gem when it is released.
@@ -23,8 +23,8 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
   # Uncomment to register a new dependency of your gem
@@ -32,6 +32,8 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "minitest", "~> 5.0"
   spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "codecov", "0.6.0"
+  spec.add_development_dependency "standard", "~> 1.20"
 
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pairing_heap
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Marcin Henryk Bartkowiak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-02-08 00:00:00.000000000 Z
+date: 2022-12-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -38,6 +38,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: codecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.20'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.20'
 description: Performant priority queue in pure ruby with support for changing priority
   using pairing heap data structure
 email:
@@ -48,7 +76,7 @@ extra_rdoc_files: []
 files:
 - ".github/workflows/main.yml"
 - ".gitignore"
-- ".rubocop.yml"
+- ".standard.yml"
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
@@ -81,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.3
+rubygems_version: 3.4.1
 signing_key:
 specification_version: 4
 summary: Performant priority queue in pure ruby with support for changing priority

data/.rubocop.yml

@@ -1,17 +0,0 @@
-AllCops:
-  Exclude:
-    - 'test/fib.rb'
-
-Style/InfiniteLoop:
-  Enabled: false
-
-Style/StringLiterals:
-  Enabled: false
-  EnforcedStyle: double_quotes
-
-Style/StringLiteralsInInterpolation:
-  Enabled: true
-  EnforcedStyle: double_quotes
-
-Layout/LineLength:
-  Max: 120