io-event 1.13.0 → 1.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a32ca73de2138ec23628217095bdfd7414f9b898e2af962922e449b297b20821
-  data.tar.gz: 67d4d9f80ec4195efdda39dc71ed5c84772336bcf1701d691115212143fd6912
+  metadata.gz: 53a9942daf957580fe332adea530a3bba659c0ec5405560078233ead0b893d11
+  data.tar.gz: d6eea90381836e4f1bf62430ae95ea0f7f2b1693683d2a114b5193f0c7a1d3f8
 SHA512:
-  metadata.gz: 12e19eb71a5f491b3513f2506474e2b184e9b4231e70cd9282b8ebdb38a214133c2d1b4fdf77d1a502c2758b29b1fe2160f55b47e060e6cd24fe36a5ed646405
-  data.tar.gz: 6ad9a898bb51eea78a28160b1d12ba8ffea073842971741c264ffad4f71e96d722289ebd840f5a2f365361926e98819b4e45014860dc4cd1eaa0f96c4fd540a1
+  metadata.gz: 9bfd04d670380038ec6a57a212f0f927b3fd748f93ac95c26e04adb1ed829a999fc02ebca56a27812c84be402b9fef576ba5d53be0df7b8f5e06bb516c70f2b6
+  data.tar.gz: ca71eac94412be0bbb953d32eb60ef1654fe24535012bc3f6f9a1a5375377175a71641c28e5ab92a5f3d44418ab50c3ef177a552cc0abe57f633e718cb2b4bc4

data/lib/io/event/priority_heap.rb

@@ -79,19 +79,112 @@ class IO
 				return self
 			end
 			
+			# Add multiple elements to the heap efficiently in O(n) time.
+			# This is more efficient than calling push multiple times (O(n log n)).
+			#
+			# @parameter elements [Array] The elements to add to the heap.
+			# @returns [self] Returns self for method chaining.
+			def concat(elements)
+				return self if elements.empty?
+				
+				# Add all elements to the array without maintaining heap property - O(n)
+				@contents.concat(elements)
+				
+				# Rebuild the heap property for the entire array - O(n)
+				heapify!
+				
+				return self
+			end
+			
 			# Empties out the heap, discarding all elements
 			def clear!
 				@contents = []
 			end
 			
+			# Remove a specific element from the heap.
+			#
+			# O(n) where n is the number of elements in the heap.
+			#
+			# @parameter element [Object] The element to remove.
+			# @returns [Object | Nil] The removed element, or nil if not found.
+			def delete(element)
+				# Find the index of the element - O(n) linear search
+				index = @contents.index(element)
+				return nil unless index
+				
+				# If it's the last element, just remove it
+				if index == @contents.size - 1
+					return @contents.pop
+				end
+				
+				# Store the value we're removing
+				removed_value = @contents[index]
+				
+				# Replace with the last element
+				last = @contents.pop
+				@contents[index] = last
+				
+				# Restore heap property - might need to bubble up or down
+				if index > 0 && @contents[index] < @contents[(index - 1) / 2]
+					# New element is smaller than parent, bubble up
+					bubble_up(index)
+				else
+					# New element might be larger than children, bubble down
+					bubble_down(index)
+				end
+				
+				# validate!
+				
+				return removed_value
+			end
+			
+			# Remove elements matching the given block condition by rebuilding the heap.
+			#
+			# This is more efficient than multiple delete operations when removing many elements.
+			#
+			# O(n) where n is the number of elements in the heap.
+			#
+			# @yields [Object] Each element in the heap for testing
+			# @returns [Integer] The number of elements removed
+			def delete_if
+				return enum_for(:delete_if) unless block_given?
+				
+				original_size = @contents.size
+				
+				# Filter out elements that match the condition - O(n)
+				@contents.reject! {|element| yield(element)}
+				
+				# If we removed elements, rebuild the heap - O(n)
+				if @contents.size < original_size
+					heapify!
+				end
+				
+				# Return number of elements removed
+				original_size - @contents.size
+			end
+			
 			# Validate the heap invariant. Every element except the root must not be smaller than its parent element. Note that it MAY be equal.
 			def valid?
-				# Notice we skip index 0 on purpose, because it has no parent
+				# Notice we skip index 0 on purpose, because it has no parent:
 				(1..(@contents.size - 1)).all? {|index| @contents[index] >= @contents[(index - 1) / 2]}
 			end
 			
 			private
 			
+			# Rebuild the heap property from an arbitrary array in O(n) time.
+			# Uses bottom-up heapify algorithm starting from the last non-leaf node.
+			def heapify!
+				return if @contents.size <= 1
+				
+				# Start from the last non-leaf node and work backwards to root:
+				last_non_leaf_index = (@contents.size / 2) - 1
+				last_non_leaf_index.downto(0) do |index|
+					bubble_down(index)
+				end
+				
+				# validate!
+			end
+			
 			# Left here for reference, but unused.
 			# def swap(i, j)
 			# 	@contents[i], @contents[j] = @contents[j], @contents[i]

data/lib/io/event/version.rb

@@ -7,6 +7,6 @@
 class IO
 	# @namespace
 	module Event
-		VERSION = "1.13.0"
+		VERSION = "1.14.0"
 	end
 end

data/readme.md

@@ -18,6 +18,10 @@ Please see the [project documentation](https://socketry.github.io/io-event/) for
 
 Please see the [project releases](https://socketry.github.io/io-event/releases/index) for all releases.
 
+### v1.14.0
+
+  - [Enhanced `IO::Event::PriorityHeap` with deletion and bulk insertion methods](https://socketry.github.io/io-event/releases/index#enhanced-io::event::priorityheap-with-deletion-and-bulk-insertion-methods)
+
 ### v1.11.2
 
   - Fix Windows build.

data/releases.md

@@ -1,5 +1,37 @@
 # Releases
 
+## v1.14.0
+
+### Enhanced `IO::Event::PriorityHeap` with deletion and bulk insertion methods
+
+The {ruby IO::Event::PriorityHeap} now supports efficient element removal and bulk insertion:
+
+  - **`delete(element)`**: Remove a specific element from the heap in O(n) time
+  - **`delete_if(&block)`**: Remove elements matching a condition with O(n) amortized bulk deletion
+  - **`concat(elements)`**: Add multiple elements efficiently in O(n) time
+
+<!-- end list -->
+
+``` ruby
+heap = IO::Event::PriorityHeap.new
+
+# Efficient bulk insertion - O(n) instead of O(n log n)
+heap.concat([5, 2, 8, 1, 9, 3])
+
+# Remove specific element
+removed = heap.delete(5)  # Returns 5, heap maintains order
+
+# Bulk removal with condition
+count = heap.delete_if { |x| x.even? }  # Removes 2, 8 efficiently
+```
+
+The `delete_if` and `concat` methods are particularly efficient for bulk operations, using bottom-up heapification to maintain the heap property in O(n) time. This provides significant performance improvements:
+
+  - **Bulk insertion**: O(n log n) → O(n) for adding multiple elements
+  - **Bulk deletion**: O(k×n) → O(n) for removing k elements
+
+Both methods maintain the heap invariant and include comprehensive test coverage with edge case validation.
+
 ## v1.11.2
 
   - Fix Windows build.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: io-event
 version: !ruby/object:Gem::Version
-  version: 1.13.0
+  version: 1.14.0
 platform: ruby
 authors:
 - Samuel Williams
@@ -116,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.0.dev
 specification_version: 4
 summary: An event loop.
 test_files: []