pairing_heap 0.1.0 → 1.0.0

data/lib/pairing_heap/version.rb

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

data/lib/pairing_heap.rb

@@ -1,18 +1,71 @@
 # frozen_string_literal: true
 
 module PairingHeap
+  module MergePairs
+    # Non-recursive implementation of method described in https://en.wikipedia.org/wiki/Pairing_heap#delete-min
+    def merge_pairs(heaps)
+      return nil if heaps.nil?
+      return heaps if heaps.next_sibling.nil?
+
+      # [H1, H2, H3, H4, H5, H6, H7] => [H1H2, H3H4, H5H6, H7]
+      pairs = nil
+      left = heaps
+      while left
+        right = left.next_sibling
+        unless right
+          left.next_sibling = pairs
+          pairs = left
+          break
+        end
+        next_val = right.next_sibling
+        right = meld(left, right)
+        right.next_sibling = pairs
+        pairs = right
+
+        left = next_val
+      end
+
+      # [H1H2, H3H4, H5H6, H7]
+      # [H1H2, H3H4, H5H67]
+      # [H1H2, H3H45H67]
+      # [H1H2H3H45H67]
+      # return H1H2H3H45H67
+      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
+
   # Pairing heap data structure implementation
   # @see https://en.wikipedia.org/wiki/Pairing_heap
   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
+        end
+        self.prev_sibling = nil
+        self.next_sibling = nil
       end
     end
     private_constant :Node
@@ -33,12 +86,17 @@ module PairingHeap
     def push(elem, priority)
       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)
+      if @root
+        @root = meld(@root, node)
+      else
+        @root = node
+      end
       self
     end
     alias enqueue push
+    alias offer push
 
     # Returns the element at the top of the heap
     #   Time Complexity: O(1)
@@ -46,6 +104,14 @@ module PairingHeap
       @root&.elem
     end
 
+    def peek_priority
+      @root&.priority
+    end
+
+    def peek_with_priority
+      [@root&.elem, @root&.priority]
+    end
+
     # Time Complexity: O(1)
     # @return [Boolean]
     def empty?
@@ -65,11 +131,10 @@ module PairingHeap
     end
     alias 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?
 
@@ -85,12 +150,18 @@ module PairingHeap
     end
     alias dequeue pop
 
+    def pop_priority
+      node = @root
+      pop
+      [node.elem, node.priority]
+    end
+
     # Changes a priority of element to a more prioritary one
     #   Time Complexity: O(1)
     #   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]
@@ -103,16 +174,16 @@ module PairingHeap
       return if node.parent.nil?
       return if @order[node.parent.priority, node.priority]
 
-      remove_from_parents_list(node)
+      node.remove_from_parents_list!
       @root = meld(node, @root)
       @root.parent = nil
       self
     end
 
-    # Removes element from the top of the heap
+    # 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]
@@ -121,39 +192,37 @@ 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
-        remove_from_parents_list(node)
+        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
 
-    private
-
-    def remove_from_parents_list(node)
-      if node.prev_sibling
-        node.prev_sibling.next_sibling = node.next_sibling
-        node.next_sibling.prev_sibling = node.prev_sibling if node.next_sibling
-      elsif node.parent.subheaps.equal?(node)
-        node.parent.subheaps = node.next_sibling
-        node.next_sibling.prev_sibling = nil if node.next_sibling
-      elsif node.next_sibling
-        node.next_sibling.prev_sibling = nil
-      end
-      node.prev_sibling = nil
-      node.next_sibling = nil
+    # Returns priority of the provided element
+    #   Time Complexity: O(1)
+    # @raise [ArgumentError] if the element is not in the heap
+    def get_priority(elem)
+      node = @nodes[elem]
+      raise ArgumentError, "Provided element is not in heap" if node.nil?
+      node.priority
     end
 
-    def meld(left, right)
-      return right if left.nil?
-      return left if right.nil?
+    private
+    include MergePairs
 
+    def meld(left, right)
       if @order[left.priority, right.priority]
         parent = left
         child = right
@@ -168,42 +237,124 @@ module PairingHeap
       child.parent = parent
       parent
     end
+  end
 
-    # Non-recursive implementation of method described in https://en.wikipedia.org/wiki/Pairing_heap#delete-min
-    def merge_pairs(heaps)
-      return nil if heaps.nil?
-      return heaps if heaps.next_sibling.nil?
+  class SimplePairingHeap
+    class Node
+      attr_accessor :elem, :priority, :subheaps, :next_sibling
+      def initialize(elem, priority)
+        @elem = elem
+        @priority = priority
+        @subheaps = nil
+        @next_sibling = nil
+      end
+    end
+    private_constant :Node
 
-      # [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
-          break
-        end
-        next_val = current.next_sibling
-        stack << meld(prev, current)
-        current = next_val
+    # @param &block Optional heap property priority comparator. `<:=.to_proc` by default
+    def initialize(&block)
+      @root = nil
+      @order = block || :<=.to_proc
+      @size = 0
+    end
+
+    # Pushes element to the heap.
+    #   Time Complexity: O(1)
+    # @param elem Element to be pushed
+    # @param priority Priority of the element
+    # @return [PairingHeap]
+    def push(elem, priority)
+      node = Node.new(elem, priority)
+      if @root
+        @root = meld(@root, node)
+      else
+        @root = node
       end
+      @size += 1
+      self
+    end
+    alias enqueue push
+    alias offer push
 
-      # [H1H2, H3H4, H5H6, H7]
-      # [H1H2, H3H4, H5H67]
-      # [H1H2, H3H45H67]
-      # [H1H2H3H45H67]
-      # return H1H2H3H45H67
-      while true
-        right = stack.pop
-        return right if stack.empty?
+    # Returns the element at the top of the heap
+    #   Time Complexity: O(1)
+    def peek
+      @root&.elem
+    end
+
+    def peek_priority
+      @root&.priority
+    end
+
+    def peek_with_priority
+      [@root&.elem, @root&.priority]
+    end
+
+    # Time Complexity: O(1)
+    # @return [Boolean]
+    def empty?
+      @root.nil?
+    end
+
+    # Time Complexity: O(1)
+    # @return [Boolean]
+    def any?
+      !@root.nil?
+    end
+
+    # Time Complexity: O(1)
+    # @return [Integer]
+    def size
+      @size
+    end
+    alias length size
+
+    # 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
+    def pop
+      raise ArgumentError, "Cannot remove from an empty heap" if @root.nil?
+      @size -= 1
+
+      elem = @root.elem
+      @root = merge_pairs(@root.subheaps)
+      @root&.next_sibling = nil
+
+      elem
+    end
+    alias dequeue pop
 
-        left = stack.pop
-        stack << meld(left, right)
+    def pop_priority
+      node = @root
+      pop
+      node.priority
+    end
+
+    def pop_with_priority
+      node = @root
+      pop
+      [node.elem, node.priority]
+    end
+
+    private
+    include MergePairs
+
+    def meld(left, right)
+      if @order[left.priority, right.priority]
+        parent = left
+        child = right
+      else
+        parent = right
+        child = left
       end
+      child.next_sibling = parent.subheaps
+      parent.subheaps = child
+      parent
     end
   end
 
+
   # Priority queue where the smallest priority is the most prioritary
   class MinPriorityQueue < PairingHeap
     def initialize
@@ -231,7 +382,7 @@ module PairingHeap
     # Changes a priority of the element to a more prioritary one
     #   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)

data/pairing_heap.gemspec

@@ -8,14 +8,15 @@ Gem::Specification.new do |spec|
   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.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.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pairing_heap
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Marcin Henryk Bartkowiak
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-02-19 00:00:00.000000000 Z
+date: 2022-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -38,7 +38,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
-description: Performant priority queue in pure Ruby with support for changing priority
+description: Performant priority queue in pure ruby with support for changing priority
   using pairing heap data structure
 email:
 - mhbartkowiak@gmail.com
@@ -65,6 +65,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/mhib/pairing_heap
   source_code_uri: https://github.com/mhib/pairing_heap
+  documentation_uri: https://rubydoc.info/gems/pairing_heap
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -80,8 +81,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.3.3
 signing_key:
 specification_version: 4
-summary: Performant priority queue in pure Ruby with support for changing priority
+summary: Performant priority queue in pure ruby with support for changing priority
 test_files: []