red-black-tree 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e609f03254a0ff34b07adf5445e91803cf4f50ffc5ba91b6288c31003218b87a
-  data.tar.gz: e1289ab4cefa28f5ae2eca05be45d5a7dbd2fa13a8a5256c81ac21511bb8e0fb
+  metadata.gz: 2b536af387a65d00a6d05596a8b209b32b500abf5cf156d5ab7169ab0149f6b2
+  data.tar.gz: 0bc6b9317ee4659228b201d5feb0c3146b356c5831ebe00a003d5d4f491020dc
 SHA512:
-  metadata.gz: 514eee78de1f75f5caaa55d285109d5e64a431a95732b3e6cabbee23e523ddd93b8b1e5e996c4ebcebce86e0ac54a15e0b88299a295515ce592254706f905e1a
-  data.tar.gz: '092aaa352db1d9d8d1082393bfff927c35dbb349ffc980720835379c27297f7d47f817edb2eb29a22103bc4beda53c683150b05756444d75b823e673161358e1'
+  metadata.gz: ea60c092e82dcecf019933df7348db451e10922437d4ac90c325fb1654ad5226738513b4a4d2e2ee45f19d2af86753c7f5932584a66ec0e90bf8c3ea0ce4836a
+  data.tar.gz: c022d30679141753341dee36142b6690756d1797fe11e2dab34b4ddeeaafcc163693a3686bf4e2a324bd60951b869d9cd6d9496d49fed0c2a9fa4c7c3335751a

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [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

data/README.md

@@ -37,13 +37,154 @@ 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#traverse_in_order`
-- `RedBlackTree#traverse_pre_order`
-- `RedBlackTree#traverse_post_order`
-- `RedBlackTree#traverse_level_order`
-- `RedBlackTree#traverse` (default in-order)
 - `RedBlackTree#max`
 - `RedBlackTree#height`
 - `RedBlackTree#clear`

data/lib/red-black-tree.rb

@@ -14,7 +14,6 @@ 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
@@ -78,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
@@ -221,11 +220,18 @@ class RedBlackTree
   # 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
-    raise ArgumentError, "data must be provided for search" unless data
+  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
 
-    _search data, @root
+      _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.
@@ -235,6 +241,64 @@ class RedBlackTree
     !!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.
@@ -263,15 +327,23 @@ class RedBlackTree
     opp_direction_child
   end
 
-  def _search data, current_node
-    return if current_node.nil? || current_node.leaf?
-    return current_node if data == current_node.data
+  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 = current_node.class.new data
-    if mock_node >= current_node
-      _search data, current_node.right
+    mock_node = node.class.new data
+    if mock_node >= node
+      _search_by_data data, node.right
     else
-      _search data, current_node.left
+      _search_by_data data, node.left
     end
   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/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

@@ -2,6 +2,7 @@
 
 require_relative "utils"
 require_relative "node/leaf_node_comparable"
+require_relative "node/data_delegation"
 require_relative "node/left_right_element_referencers"
 
 class RedBlackTree
@@ -13,6 +14,7 @@ class RedBlackTree
     end
 
     include Comparable
+    include DataDelegation
 
     # @return [any] the data/value representing the node
     attr_reader :data

data/lib/red_black_tree/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class RedBlackTree
-  VERSION = "0.1.2"
+  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.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Joshua Young
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-14 00:00:00.000000000 Z
+date: 2024-10-21 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -23,6 +23,7 @@ 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
@@ -51,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