rbtree-ruby 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13b088e9f0f8ab5cf80a77b8f9b8e1af73b94b33bdff90115fe575def2c54b11
-  data.tar.gz: 51636a7c22c4ccc70d2ac14bafc58a39bbccac7599a704506c280d8d39345117
+  metadata.gz: f3c97bfa59aaaa7bbc03f272fdc5e383b258f529134f1d2a79fd3758d1d53b02
+  data.tar.gz: fa9c8df14da95bf4224164d720c90981c1c68ef96e5cb544007327b9a1564b11
 SHA512:
-  metadata.gz: e543801d0b22de4ee8654f7b8164121c2107ccda64bc16f47d034e98526703e4aa444e03cecd225bddb9aa9fc5547813bcd1bc73cd4a4048df98eee5d41a2fc6
-  data.tar.gz: 6d6986550fe2293e971558e65119f230c3eb26e8f43f8af77fe8bf666d5df337c6bf23e36a4e4fd7e8aee86287b6f58579e48a637e66d27a6e80ab66b0010ed4
+  metadata.gz: e856b4d10d326c3d3261d21044db760b41447dd01e1eb22bff4dfe1ac07e71f709792b75a9ee48ddc3195f06993fd86e8434511b3f2f0eaafbcf0827da05aa1e
+  data.tar.gz: 10e8c1af8787b201c73a64557ba86304867b601daae13ad816771b87e52a81e30bc94dbeda5accc1e224a55d397ae28e0325918d61d8d4db40ee09cdd83876fa

data/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.3] - 2026-01-14
+
+### Added
+- **Bulk Insert**: `insert` now supports bulk insertion from Hash, Array of pairs, Enumerator, or Block.
+  - `tree.insert({1 => 'one', 2 => 'two'})`
+  - `tree.insert([[1, 'one'], [2, 'two']])`
+  - `tree.insert { source_data }`
+- **Flexible Initialization**: `RBTree.new` and `MultiRBTree.new` now accept bulk data and an `overwrite:` option.
+  - `RBTree.new([[1, 'a'], [1, 'b']], overwrite: false)`
+
 ## [0.2.2] - 2026-01-14
 
 ### Changed

data/README.ja.md

@@ -2,8 +2,7 @@
 
 🌍 *[English](README.md) | [日本語](README.ja.md)*
 
-Red-Black Tree（赤黒木）データ構造のピュアRuby実装です。挿入、削除、検索操作がO(log n)の時間計算量で実行できる、
-効率的な順序付きキーバリューストレージを提供します。
+Red-Black Tree（赤黒木）データ構造のピュアRuby実装です。挿入、削除、検索操作がO(log n)の時間計算量で実行できる、効率的な順序付きキーバリューストレージを提供します。
 
 ## 特徴
 
@@ -43,13 +42,18 @@ require 'rbtree'
 # 空のツリーを作成
 tree = RBTree.new
 
-# データで初期化
+# データで初期化（バルク挿入）
 tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
 tree = RBTree[[5, 'five'], [4, 'four']]
+tree = RBTree.new do # ブロック初期化
+  data_source.each { |data| [data.time, data.content] } 
+end
 
 # 値の挿入と取得
 tree.insert(10, 'ten')
 tree[20] = 'twenty'
+# バルク挿入
+tree.insert({30 => 'thirty', 40 => 'forty'})
 puts tree[10]  # => "ten"
 
 # ソート順でイテレーション
@@ -138,6 +142,8 @@ tree.nearest(8)   # => [10, "ten"]
 
 ### 前後キー検索
 
+ツリーの中で次のキーまたは前のキーを検索します。
+
 ```ruby
 tree = RBTree.new({1 => 'one', 3 => 'three', 5 => 'five', 7 => 'seven'})
 
@@ -202,8 +208,8 @@ tree.max(last: true)      # => [2, "b"]      (最大キーの最後の値)
 
 - `insert(key, value)` - O(log n)
 - `delete(key)` - O(log n)
-- `get(key)` / `[]` - **O(1)** (ハイブリッドハッシュインデックス)
-- `has_key?` - **O(1)** (ハイブリッドハッシュインデックス)
+- `get(key)` / `[]` - **O(1)** (内部ハッシュインデックスによる超高速アクセス)
+- `has_key?` - **O(1)** (内部ハッシュインデックスによる超高速チェック)
 - `min` - **O(1)**
 - `max` - O(log n)
 - `shift` / `pop` - O(log n)
@@ -227,7 +233,7 @@ RBTreeは内部的な**メモリプール**を使用してノードオブジェ
 | **範囲クエリ** | **O(log n + k)** | O(n) フィルター | **〜540倍高速** | 部分木へ直接ジャンプ vs 全件スキャン |
 | **最小値抽出** | **O(log n)** | O(n) 検索 | **〜160倍高速** | 連続的なリバランス vs 全件スキャン |
 | **ソート済みイテレーション** | **O(n)** | O(n log n) | **無料** | 常にソート済み vs 明示的な`sort` |
-| **キー検索** | **O(1)** | O(1) | **同等** | ハイブリッドハッシュインデックス |
+| **キー検索** | **O(1)** | O(1) | **同等** | **ハイブリッドハッシュインデックスにより、Hashと同等のO(1)検索速度を実現** |
 
 ### RBTreeを使うべき場面
 

data/README.md

@@ -2,8 +2,7 @@
 
 🌍 *[English](README.md) | [日本語](README.ja.md)*
 
-A pure Ruby implementation of the Red-Black Tree data structure, providing efficient ordered
-key-value storage with O(log n) time complexity for insertion, deletion, and lookup operations.
+A pure Ruby implementation of the Red-Black Tree data structure, providing efficient ordered key-value storage with O(log n) time complexity for insertion, deletion, and lookup operations.
 
 ## Features
 
@@ -43,13 +42,18 @@ require 'rbtree'
 # Create an empty tree
 tree = RBTree.new
 
-# Or initialize with data
+# Or initialize with data (Bulk Insert)
 tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
 tree = RBTree[[5, 'five'], [4, 'four']]
+tree = RBTree.new do # Block initialization
+  data_source.each { |data| [data.time, data.content] } 
+end
 
 # Insert and retrieve values
 tree.insert(10, 'ten')
 tree[20] = 'twenty'
+# Bulk insert
+tree.insert({30 => 'thirty', 40 => 'forty'})
 puts tree[10]  # => "ten"
 
 # Iterate in sorted order
@@ -229,7 +233,7 @@ For ordered and spatial operations, RBTree is not just faster—it is in a compl
 | **Range Queries** | **O(log n + k)** | O(n) filter | **~540x faster** | Direct subtree jump vs full scan |
 | **Min Extraction** | **O(log n)** | O(n) search | **~160x faster** | Continuous rebalancing vs full scan |
 | **Sorted Iteration** | **O(n)** | O(n log n) | **FREE** | Always sorted vs explicit `sort` |
-| **Key Lookup** | **O(1)** | O(1) | **Equal** | Optimized Hybrid Hash Index |
+| **Key Lookup** | **O(1)** | O(1) | **Equal** | **Hybrid Hash Index provides O(1) access like standard Hash** |
 
 ### When to Use RBTree
 

data/lib/rbtree/version.rb

@@ -2,5 +2,5 @@
 
 class RBTree
   # The version of the rbtree-ruby gem
-  VERSION = "0.2.2"
+  VERSION = "0.2.3"
 end

data/lib/rbtree.rb

@@ -72,11 +72,15 @@ class RBTree
 
   # Initializes a new RBTree.
   #
-  # The tree can be initialized empty or populated with initial data from a Hash or Array.
+  # The tree can be initialized empty or populated with initial data from a Hash, Array, or Enumerator.
+  # A block can also be provided to supply the initial data.
   #
   # @param args [Hash, Array, nil] optional initial data
+  # @param overwrite [Boolean] whether to overwrite existing keys (default: true)
+  # @yieldreturn [Object] optional initial data
   #   - If a Hash is provided, each key-value pair is inserted into the tree
   #   - If an Array is provided, it should contain [key, value] pairs
+  #   - If a block is provided, it is yielded to get the source data
   #   - If no arguments are provided, an empty tree is created
   # @raise [ArgumentError] if arguments are invalid
   # @example Create an empty tree
@@ -85,7 +89,9 @@ class RBTree
   #   tree = RBTree.new({1 => 'one', 2 => 'two'})
   # @example Create from an array
   #   tree = RBTree.new([[1, 'one'], [2, 'two']])
-  def initialize(*args)
+  # @example Create with overwrite: false
+  #   tree = RBTree.new([[1, 'one'], [1, 'uno']], overwrite: false)
+  def initialize(*args, overwrite: true, &block)
     @nil_node = Node.new
     @nil_node.color = Node::BLACK
     @nil_node.left = @nil_node
@@ -96,19 +102,8 @@ class RBTree
     @node_pool = []   # Memory pool for recycling nodes
     @size = 0
 
-    if args.any?
-      source = args.size == 1 ? args.first : args
-      case source
-      when Hash
-        source.each { |k, v| insert(k, v) }
-      when Array
-        source.each do |arg| 
-          key, value = arg
-          insert(key, value)
-        end
-      else
-        raise ArgumentError, "Invalid arguments"
-      end
+    if args.size > 0 || block_given?
+      insert(*args, overwrite: overwrite, &block)
     end
   end
 
@@ -211,63 +206,67 @@ class RBTree
     n == @nil_node ? nil : n.pair
   end
 
-  # Inserts or updates a key-value pair in the tree.
+  # Inserts one or more key-value pairs into the tree.
+  #
+  # This method supports both single entry insertion and bulk insertion.
+  #
+  # Single insertion:
+  #   insert(key, value, overwrite: true)
+  #
+  # Bulk insertion:
+  #   insert(hash, overwrite: true)
+  #   insert(array_of_pairs, overwrite: true)
+  #   insert(enumerator, overwrite: true)
+  #   insert { data_source }
   #
   # If the key already exists and overwrite is true (default), the value is updated.
   # If overwrite is false and the key exists, the operation returns nil without modification.
   #
-  # @param key [Object] the key to insert (must implement <=>)
-  # @param value [Object] the value to associate with the key
+  # @param args [Object] key (and value) or source object
   # @param overwrite [Boolean] whether to overwrite existing keys (default: true)
-  # @return [Boolean, nil] true if inserted/updated, nil if key exists and overwrite is false
-  # @example
-  #   tree = RBTree.new
-  #   tree.insert(1, 'one')        # => true
-  #   tree.insert(1, 'ONE')        # => true (overwrites)
-  #   tree.insert(1, 'uno', overwrite: false)  # => nil (no change)
-  #   tree[2] = 'two'              # using alias
-  def insert(key, value, overwrite: true)
-    if (node = @hash_index[key])
-      return nil unless overwrite
-      node.value = value
-      return true
-    end
-    y = @nil_node
-    x = @root
-    while x != @nil_node
-      y = x
-      cmp = key <=> x.key
-      if cmp == 0
-        return nil unless overwrite
-        x.value = value
-        return true
-      elsif cmp < 0
-        x = x.left
+  # @yieldreturn [Object] data source for bulk insertion
+  # @return [Boolean, nil] true if inserted/updated, nil if key exists and overwrite is false (for single insert)
+  # @example Single insert
+  #   tree.insert(1, 'one')
+  # @example Bulk insert from Hash
+  #   tree.insert({1 => 'one', 2 => 'two'})
+  # @example Bulk insert from Array
+  #   tree.insert([[1, 'one'], [2, 'two']])
+  def insert(*args, overwrite: true, &block)
+    if args.size == 2
+      key, value = args
+      insert_entry(key, value, overwrite: overwrite)
+    else
+      source = nil
+      if args.empty? && block_given?
+        source = yield
+      elsif args.size == 1
+        source = args[0]
+      elsif args.empty?
+        return # No-op
       else
-        x = x.right
+        raise ArgumentError, "wrong number of arguments (given #{args.size}, expected 0..2)"
+      end
+
+      return if source.nil?
+
+      unless source.respond_to?(:each)
+        raise ArgumentError, "Source must be iterable"
+      end
+
+      source.each do |*pair|
+        key, value = nil, nil
+        if pair.size == 1 && pair[0].is_a?(Array)
+          key, value = pair[0]
+          raise ArgumentError, "Invalid pair size: #{pair[0].size} (expected 2)" unless pair[0].size == 2
+        elsif pair.size == 2
+          key, value = pair
+        else
+          raise ArgumentError, "Invalid pair format: #{pair.inspect}"
+        end
+        insert_entry(key, value, overwrite: overwrite)
       end
     end
-    z = allocate_node(key, value, Node::RED, @nil_node, @nil_node, @nil_node)
-    z.parent = y
-    if y == @nil_node
-      @root = z
-    elsif (key <=> y.key) < 0
-      y.left = z
-    else
-      y.right = z
-    end
-    z.left = @nil_node
-    z.right = @nil_node
-    z.color = Node::RED
-    insert_fixup(z)
-    @size += 1
-    
-    if @min_node == @nil_node || (key <=> @min_node.key) < 0
-      @min_node = z
-    end
-    
-    @hash_index[key] = z  # Add to hash index
-    true
   end
   alias_method :[]=, :insert
 
@@ -518,8 +517,58 @@ class RBTree
     true
   end
 
-  # @!visibility private
-  private
+  # @!visibility protected
+  protected
+
+  # Inserts a single key-value pair.
+  #
+  # @param key [Object] the key to insert
+  # @param value [Object] the value to associate with the key
+  # @param overwrite [Boolean] whether to overwrite existing keys (default: true)
+  # @return [Boolean, nil] true if inserted/updated, nil if key exists and overwrite is false
+  def insert_entry(key, value, overwrite: true)
+    if (node = @hash_index[key])
+      return nil unless overwrite
+      node.value = value
+      return true
+    end
+    y = @nil_node
+    x = @root
+    while x != @nil_node
+      y = x
+      cmp = key <=> x.key
+      if cmp == 0
+        return nil unless overwrite
+        x.value = value
+        return true
+      elsif cmp < 0
+        x = x.left
+      else
+        x = x.right
+      end
+    end
+    z = allocate_node(key, value, Node::RED, @nil_node, @nil_node, @nil_node)
+    z.parent = y
+    if y == @nil_node
+      @root = z
+    elsif (key <=> y.key) < 0
+      y.left = z
+    else
+      y.right = z
+    end
+    z.left = @nil_node
+    z.right = @nil_node
+    z.color = Node::RED
+    insert_fixup(z)
+    @size += 1
+    
+    if @min_node == @nil_node || (key <=> @min_node.key) < 0
+      @min_node = z
+    end
+    
+    @hash_index[key] = z  # Add to hash index
+    true
+  end
 
   # Traverses the tree in ascending order (in-order traversal).
   #
@@ -1377,12 +1426,13 @@ class MultiRBTree < RBTree
   #
   # @param key [Object] the key (must implement <=>)
   # @param value [Object] the value to insert
+  # @param overwrite [Boolean] ignored for MultiRBTree which always appends
   # @return [Boolean] always returns true
   # @example
   #   tree = MultiRBTree.new
   #   tree.insert(1, 'first')
   #   tree.insert(1, 'second')  # adds another value for key 1
-  def insert(key, value)
+  def insert_entry(key, value, **)
     if (node = @hash_index[key])
       node.value << value
       @size += 1
@@ -1527,7 +1577,8 @@ class MultiRBTree < RBTree
     @hash_index[key]&.value&.each { |v| yield v }
   end
 
-  private
+  # @!visibility protected
+  protected
 
   def traverse_range_asc(...)
     super { |k, vals| vals.each { |v| yield k, v } }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rbtree-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - Masahito Suzuki