red-black-tree 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61a6b03da9c3a60295a236ee3a62996b780cb19dfc18f85fd050e5eb788cf2a0
-  data.tar.gz: 05a1325effc0127636d0b9ad4e837e1b319c248488b20b4023541bbdea940f29
+  metadata.gz: 2b536af387a65d00a6d05596a8b209b32b500abf5cf156d5ab7169ab0149f6b2
+  data.tar.gz: 0bc6b9317ee4659228b201d5feb0c3146b356c5831ebe00a003d5d4f491020dc
 SHA512:
-  metadata.gz: 19aaf38a058f020b0638ddb99cfa3ecaa51d9bc6a0a0f82046f577898e9de6cf203a3d8e48c2d3dbba60bbf3b555ecd8c47e5cffbe9f8cf0840740af34698924
-  data.tar.gz: 759e5478416fc7c5a80e4c0775d4df53d9640ddc356b3eea65595ae3657d0a8314c0ff7273799c8f6f0ed31ca6b5bf3e2431b31008f17537445aca2b6b694807
+  metadata.gz: ea60c092e82dcecf019933df7348db451e10922437d4ac90c325fb1654ad5226738513b4a4d2e2ee45f19d2af86753c7f5932584a66ec0e90bf8c3ea0ce4836a
+  data.tar.gz: c022d30679141753341dee36142b6690756d1797fe11e2dab34b4ddeeaafcc163693a3686bf4e2a324bd60951b869d9cd6d9496d49fed0c2a9fa4c7c3335751a

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.1.3] - 2024-10-21
+
+- Make `RedBlackTree#left_most_node` public
+- Add `RedBlackTree#traverse_pre_order`
+- Add `RedBlackTree#traverse_in_order`
+- Add `RedBlackTree#traverse_post_order`
+- Add `RedBlackTree#traverse_level_order`
+- Add `RedBlackTree#traverse`, alias of `RedBlackTree#traverse_in_order`
+- Extend `RedBlackTree#search` to accept a block
+- Delegate missing `RedBlackTree::Node` methods to its `#data`
+
+## [0.1.2] - 2024-09-08
+
+- Fix a bunch of issues in `RedBlackTree#insert!` and `RedBlackTree#delete!` algorithms
+- Fix `RedBlackTree::LeafNode`s being marked red
+- Handle comparison with `RedBlackTree::LeafNode` in subclasses of `RedBlackTree::Node`
+- Add `RedBlackTree#include?`
+- Add `RedBlackTree#search`
+- Alias `RedBlackTree#left_most_node` as `RedBlackTree#min`
+
 ## [0.1.1] - 2024-08-04
 
 - Update `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` in README

data/README.md

@@ -17,20 +17,17 @@ If bundler is not being used to manage dependencies, install the gem by executin
 ```ruby
 Work = Struct.new :min_latency, keyword_init: true
 
+# Needs to be implemented by you
 class WorkNode < RedBlackTree::Node
   def <=> other
-    if other.instance_of? RedBlackTree::LeafNode
-      1
-    else
-      self.data.min_latency <=> other.data.min_latency
-    end
+    self.data.min_latency <=> other.data.min_latency
   end
 end
 
 tree = RedBlackTree.new
 
-tree << WorkNode.new(Work.new min_latency: 1.2)
 tree << WorkNode.new(Work.new min_latency: 0.8)
+tree << WorkNode.new(Work.new min_latency: 1.2)
 tree << WorkNode.new(Work.new min_latency: 0.8)
 tree << WorkNode.new(Work.new min_latency: 0.4)
 
@@ -40,6 +37,158 @@ until tree.empty?
 end
 ```
 
+## Performance
+
+> [!NOTE]
+> Red-black trees are designed for specific use cases and are not intended as a general-purpose data structure. The
+comparisons below are provided merely to illustrate the performance characteristics of the gem. However, it is important
+to note that the benchmarks do not take into account the self-balancing nature of red-black trees.
+
+### Sort and iterate 10,000 elements
+
+```ruby
+require 'benchmark/ips'
+
+Work = Struct.new :min_latency, keyword_init: true
+
+class WorkNode < RedBlackTree::Node
+  def <=> other
+    self.data.min_latency <=> other.data.min_latency
+  end
+end
+
+sample_data = 10_000.times.map { Work.new(min_latency: rand(1_000)) }
+
+Benchmark.ips do |x|
+  x.report("RedBlackTree") do
+    tree = RedBlackTree.new
+    sample_data.each { |work| tree << WorkNode.new(work); }
+    tree.shift until tree.empty?
+  end
+
+  # 1:1 comparison
+  x.report("Array (gradual sort)") do
+    array = []
+    sample_data.each { |work| array << work; array.sort_by!(&:min_latency); }
+    array.shift until array.empty?
+  end
+
+  x.report("Array (single sort)") do
+    array = []
+    sample_data.each { |work| array << work; }
+    array.sort_by!(&:min_latency)
+    array.shift until array.empty?
+  end
+
+  x.compare!
+end
+
+#=> ruby 3.3.5 (2024-09-03 revision ef084cc8f4) [arm64-darwin24]
+#=> Warming up --------------------------------------
+#=>         RedBlackTree     1.000 i/100ms
+#=> Array (gradual sort)     1.000 i/100ms
+#=>  Array (single sort)    78.000 i/100ms
+#=> Calculating -------------------------------------
+#=>         RedBlackTree      5.417 (± 0.0%) i/s  (184.61 ms/i) -     28.000 in   5.172532s
+#=> Array (gradual sort)      0.268 (± 0.0%) i/s     (3.74 s/i) -      2.000 in   7.473005s
+#=>  Array (single sort)    768.691 (± 2.2%) i/s    (1.30 ms/i) -      3.900k in   5.076337s
+#=>
+#=> Comparison:
+#=>  Array (single sort):      768.7 i/s
+#=>         RedBlackTree:        5.4 i/s - 141.91x  slower
+#=> Array (gradual sort):        0.3 i/s - 2872.03x  slower
+```
+
+### Sort and search 10,000 elements
+
+```ruby
+require 'benchmark/ips'
+
+Work = Struct.new :min_latency, keyword_init: true
+
+class WorkNode < RedBlackTree::Node
+  def <=> other
+    self.data.min_latency <=> other.data.min_latency
+  end
+end
+
+sample_data = 10_000.times.map { Work.new(min_latency: rand(1_000)) }
+search_sample = sample_data.sample
+
+Benchmark.ips do |x|
+  x.report("RedBlackTree#search") do
+    tree = RedBlackTree.new
+    sample_data.each { |work| tree << WorkNode.new(work); }
+    raise unless tree.search search_sample
+  end
+
+  # 1:1 comparison
+  x.report("Array#find (gradual sort)") do
+    array = []
+    sample_data.each { |work| array << work; array.sort_by!(&:min_latency); }
+    raise unless array.find { |work| work.min_latency == search_sample.min_latency }
+  end
+
+  x.report("Array#find (single sort)") do
+    array = []
+    sample_data.each { |work| array << work; }
+    array.sort_by!(&:min_latency)
+    raise unless array.find { |work| work.min_latency == search_sample.min_latency }
+  end
+
+  # 1:1 comparison
+  x.report("Array#bsearch (gradual sort)") do
+    array = []
+    sample_data.each { |work| array << work; array.sort_by!(&:min_latency); }
+    raise unless array.bsearch { |work| search_sample.min_latency <= work.min_latency }
+  end
+
+  x.report("Array#bsearch (single sort)") do
+    array = []
+    sample_data.each { |work| array << work; }
+    array.sort_by!(&:min_latency)
+    raise unless array.bsearch { |work| search_sample.min_latency <= work.min_latency }
+  end
+
+  x.compare!
+end
+
+#=> ruby 3.3.5 (2024-09-03 revision ef084cc8f4) [arm64-darwin24]
+#=> Warming up --------------------------------------
+#=>  RedBlackTree#search     1.000 i/100ms
+#=> Array#find (gradual sort)
+#=>                          1.000 i/100ms
+#=> Array#find (single sort)
+#=>                         69.000 i/100ms
+#=> Array#bsearch (gradual sort)
+#=>                          1.000 i/100ms
+#=> Array#bsearch (single sort)
+#=>                         89.000 i/100ms
+#=> Calculating -------------------------------------
+#=>  RedBlackTree#search     12.926 (± 0.0%) i/s   (77.36 ms/i) -     65.000 in   5.030736s
+#=> Array#find (gradual sort)
+#=>                           0.262 (± 0.0%) i/s     (3.81 s/i) -      2.000 in   7.623953s
+#=> Array#find (single sort)
+#=>                         690.631 (± 1.0%) i/s    (1.45 ms/i) -      3.519k in   5.095823s
+#=> Array#bsearch (gradual sort)
+#=>                           0.267 (± 0.0%) i/s     (3.75 s/i) -      2.000 in   7.492482s
+#=> Array#bsearch (single sort)
+#=>                         895.413 (± 1.7%) i/s    (1.12 ms/i) -      4.539k in   5.070590s
+#=>
+#=> Comparison:
+#=> Array#bsearch (single sort):      895.4 i/s
+#=> Array#find (single sort):         690.6 i/s - 1.30x  slower
+#=> RedBlackTree#search:               12.9 i/s - 69.27x  slower
+#=> Array#bsearch (gradual sort):       0.3 i/s - 3354.39x  slower
+#=> Array#find (gradual sort):          0.3 i/s - 3412.57x  slower
+```
+
+## WIP Features
+
+- `RedBlackTree#max`
+- `RedBlackTree#height`
+- `RedBlackTree#clear`
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` to run the

data/lib/red-black-tree.rb

@@ -14,9 +14,9 @@ class RedBlackTree
   # @return [RedBlackTree::Node, nil] the root node
   attr_reader :root
 
-  # @private
   # @return [RedBlackTree::Node, nil] the left most node
   attr_reader :left_most_node
+  alias_method :min, :left_most_node
 
   def initialize
     @size = 0
@@ -41,8 +41,13 @@ class RedBlackTree
   #
   # @return [RedBlackTree::Node, nil] the removed node
   def shift
-    node = @left_most_node
-    delete! node if node
+    return unless @left_most_node
+
+    node = @left_most_node.dup
+    node.colour = node.parent = node.left = node.right = nil
+
+    delete! @left_most_node
+
     node
   end
 
@@ -72,8 +77,8 @@ class RedBlackTree
   #
   # @private ideally this is only used internally e.g. in #<< which has context on the ideal location for the node
   # @param node [RedBlackTree::Node] the node to be inserted
-  # @param target_parent [RedBlackTree::Node, nil] the parent under which the node should be inserted
-  # @param direction ["left", "right", nil] the direction of the node relative to the parent
+  # @param target_parent [RedBlackTree::Node] the parent under which the node should be inserted
+  # @param direction ["left", "right"] the direction of the node relative to the parent
   # @return [RedBlackTree] self
   def insert! node, target_parent = nil, direction = nil
     raise ArgumentError, "cannot insert leaf node" if node.instance_of? LeafNode
@@ -85,8 +90,6 @@ class RedBlackTree
       raise ArgumentError, "Target parent already has #{direction} child" if (child = target_parent[direction]) && child.valid?
     end
 
-    opp_direction = opposite_direction direction if direction
-
     node.parent = nil
     node.left = LeafNode.new
     node.left.parent = node
@@ -108,17 +111,16 @@ class RedBlackTree
           node.parent.parent.red!
           node = node.parent.parent
         else
-          if node.position == direction
-            node = node.parent
-            rotate_sub_tree! node, opp_direction
+          opp_direction = node.opposite_position
+          if node.parent.position == opp_direction
+            rotate_sub_tree! node.parent, opp_direction
+            node = node[opp_direction]
           end
 
+          opp_direction = node.opposite_position
+          rotate_sub_tree! node.parent.parent, opp_direction
           node.parent.black!
-
-          if node.parent.parent
-            node.parent.parent.red!
-            rotate_sub_tree! node.parent.parent, direction
-          end
+          node.parent[opp_direction].red!
         end
 
         @root.black!
@@ -140,6 +142,8 @@ class RedBlackTree
   def delete! node
     raise ArgumentError, "cannot delete leaf node" if node.instance_of? LeafNode
 
+    original_node = node
+
     if node.children_are_valid?
       successor = node.left
       successor = successor.left until successor.left.leaf?
@@ -160,19 +164,19 @@ class RedBlackTree
       if is_root? node
         @root = nil
       elsif node.red?
-        leaf = LeafNode.new
-        node.swap_position_with! leaf
+        node.swap_position_with! LeafNode.new
       else
-        direction = node.position
-        opp_direction = opposite_direction direction
-
         loop do
-          if node.sibling.valid? && node.sibling.red?
+          if node.sibling && node.sibling.valid? && node.sibling.red?
             node.parent.red!
             node.sibling.black!
-            rotate_sub_tree! node.parent, direction
+            rotate_sub_tree! node.parent, node.position
+          end
 
-            next
+          if node.close_nephew && node.close_nephew.valid? && node.close_nephew.red?
+            node.sibling.red! unless node.sibling.leaf?
+            node.close_nephew.black!
+            rotate_sub_tree! node.sibling, node.opposite_position
           end
 
           if node.distant_nephew && node.distant_nephew.valid? && node.distant_nephew.red?
@@ -182,35 +186,30 @@ class RedBlackTree
             end
             node.parent.black!
             node.distant_nephew.black!
-            rotate_sub_tree! node.parent, direction
+            rotate_sub_tree! node.parent, node.position
 
             break
           end
 
-          if node.close_nephew && node.close_nephew.valid? && node.close_nephew.red?
-            node.sibling.red!
-            node.close_nephew.black!
-            rotate_sub_tree! node.sibling, opp_direction
+          if node.parent && node.parent.red?
+            node.sibling.red! unless node.sibling.leaf?
+            node.parent.black!
 
-            next
+            break
           end
 
-          if node.parent.red?
+          if node.sibling && !node.sibling.leaf?
             node.sibling.red!
-            node.parent.black!
-
-            break
           end
 
-          break
+          break unless node = node.parent
         end
 
-        leaf = LeafNode.new
-        node.swap_position_with! leaf
+        original_node.swap_position_with! LeafNode.new
       end
     end
 
-    node.validate_free!
+    original_node.validate_free!
 
     decrement_size!
     update_left_most_node!
@@ -218,12 +217,90 @@ class RedBlackTree
     self
   end
 
-  private
+  # Searches for a node which matches the given data/value.
+  #
+  # @param data [any] the data to search for
+  # @yield [RedBlackTree::Node] the block to be used for comparison
+  # @return [RedBlackTree::Node, nil] the matching node
+  def search data = nil, &block
+    if block_given?
+      raise ArgumentError, "provide either data or block, not both" if data
+
+      _search_by_block block, @root
+    else
+      raise ArgumentError, "data must be provided for search" unless data
 
-  def is_root? node
-    node.object_id == @root.object_id
+      _search_by_data data, @root
+    end
+  end
+
+  # Returns true if there is a node which matches the given data/value, and false if there is not.
+  #
+  # @return [true, false]
+  def include? data
+    !!search(data)
+  end
+
+  # Traverses the tree in pre-order and yields each node.
+  #
+  # @param node [RedBlackTree::Node] the node to start the traversal from
+  # @yield [RedBlackTree::Node] the block to be executed for each node
+  # @return [void]
+  def traverse_pre_order node = @root, &block
+    return if node.nil? || node.leaf?
+
+    block.call node
+    traverse_pre_order node.left, &block
+    traverse_pre_order node.right, &block
+  end
+
+  # Traverses the tree in in-order and yields each node.
+  #
+  # @param node [RedBlackTree::Node] the node to start the traversal from
+  # @yield [RedBlackTree::Node] the block to be executed for each node
+  # @return [void]
+  def traverse_in_order node = @root, &block
+    return if node.nil? || node.leaf?
+
+    traverse_in_order node.left, &block
+    block.call node
+    traverse_in_order node.right, &block
+  end
+  alias_method :traverse, :traverse_in_order
+
+  # Traverses the tree in post-order and yields each node.
+  #
+  # @param node [RedBlackTree::Node] the node to start the traversal from
+  # @yield [RedBlackTree::Node] the block to be executed for each node
+  # @return [void]
+  def traverse_post_order node = @root, &block
+    return if node.nil? || node.leaf?
+
+    traverse_post_order node.left, &block
+    traverse_post_order node.right, &block
+    block.call node
+  end
+
+  # Traverses the tree in level-order and yields each node.
+  #
+  # @yield [RedBlackTree::Node] the block to be executed for each node
+  # @return [void]
+  def traverse_level_order &block
+    return if @root.nil?
+
+    queue = [@root]
+    until queue.empty?
+      node = queue.shift
+      next if node.nil? || node.leaf?
+
+      block.call node
+      queue << node.left
+      queue << node.right
+    end
   end
 
+  private
+
   # Rotates a (sub-)tree starting from the given node in the given direction.
   #
   # @param node [RedBlackTree::Node] the root node of the sub-tree
@@ -250,6 +327,30 @@ class RedBlackTree
     opp_direction_child
   end
 
+  def _search_by_block block, node
+    traverse node do |current|
+      next if current.leaf?
+
+      return current if block.call current
+    end
+  end
+
+  def _search_by_data data, node
+    return if node.nil? || node.leaf?
+    return node if data == node.data
+
+    mock_node = node.class.new data
+    if mock_node >= node
+      _search_by_data data, node.right
+    else
+      _search_by_data data, node.left
+    end
+  end
+
+  def is_root? node
+    node && @root && node.object_id == @root.object_id
+  end
+
   def increment_size!
     @size += 1
   end

data/lib/red_black_tree/node/data_delegation.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class RedBlackTree
+  module DataDelegation
+    def method_missing method_name, *args, &block
+      if @data.respond_to? method_name
+        @data.public_send method_name, *args, &block
+      else
+        super
+      end
+    end
+
+    def respond_to_missing? method_name, include_private = false
+      @data.respond_to? method_name, include_private || super
+    end
+  end
+end

data/lib/red_black_tree/node/leaf_node_comparable.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class RedBlackTree
+  module LeafNodeComparable # @private
+    def <=> other
+      if other.instance_of? ::RedBlackTree::LeafNode
+        1
+      else
+        super
+      end
+    end
+  end
+end

data/lib/red_black_tree/node/left_right_element_referencers.rb

@@ -7,7 +7,7 @@ class RedBlackTree
         case direction
         when Node::LEFT then @left
         when Node::RIGHT then @right
-        else raise ArgumentError, "Direction must be one of #{DIRECTIONS}"
+        else raise ArgumentError, "Direction must be one of #{Implementation::DIRECTIONS}"
         end
       end
 
@@ -15,7 +15,7 @@ class RedBlackTree
         case direction
         when Node::LEFT then @left = node
         when Node::RIGHT then @right = node
-        else raise ArgumentError, "Direction must be one of #{DIRECTIONS}"
+        else raise ArgumentError, "Direction must be one of #{Implementation::DIRECTIONS}"
         end
       end
     end

data/lib/red_black_tree/node.rb

@@ -1,11 +1,20 @@
 # frozen_string_literal: true
 
 require_relative "utils"
+require_relative "node/leaf_node_comparable"
+require_relative "node/data_delegation"
 require_relative "node/left_right_element_referencers"
 
 class RedBlackTree
   class Node
+    class << self
+      def inherited subclass
+        subclass.prepend LeafNodeComparable
+      end
+    end
+
     include Comparable
+    include DataDelegation
 
     # @return [any] the data/value representing the node
     attr_reader :data
@@ -42,8 +51,8 @@ class RedBlackTree
       RIGHT = "right"
       DIRECTIONS = [LEFT, RIGHT].freeze
 
-      attr_reader :colour
       attr_writer :data
+      attr_accessor :colour
       attr_accessor :tree, :parent
       attr_accessor :left, :right
       include LeftRightElementReferencers
@@ -65,9 +74,9 @@ class RedBlackTree
       def position
         return unless @parent
 
-        case self
-        when @parent.left then LEFT
-        when @parent.right then RIGHT
+        case self.object_id
+        when @parent.left.object_id then LEFT
+        when @parent.right.object_id then RIGHT
         else raise StructuralError, "Disowned by parent"
         end
       end
@@ -140,13 +149,13 @@ class RedBlackTree
         self_position = position
         other_position = other_node.position
 
-        if other_node.parent == self
+        if other_node.parent.object_id == self.object_id
           self[other_position] = other_node[other_position]
           other_node[other_position] = self
 
           other_node.parent = @parent
           @parent = other_node
-        elsif other_node == @parent
+        elsif other_node.object_id == @parent.object_id
           other_node[self_position] = self[self_position]
           self[self_position] = other_node
 

data/lib/red_black_tree/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class RedBlackTree
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: red-black-tree
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Joshua Young
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-08-03 00:00:00.000000000 Z
+date: 2024-10-21 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -23,7 +23,9 @@ files:
 - README.md
 - lib/red-black-tree.rb
 - lib/red_black_tree/node.rb
+- lib/red_black_tree/node/data_delegation.rb
 - lib/red_black_tree/node/leaf_node.rb
+- lib/red_black_tree/node/leaf_node_comparable.rb
 - lib/red_black_tree/node/left_right_element_referencers.rb
 - lib/red_black_tree/utils.rb
 - lib/red_black_tree/version.rb
@@ -50,7 +52,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.15
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Red-Black Tree Data Structure for Ruby