rbtree-ruby 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cdac6cf721ca88b6fa05ccc11997093f9dee8d64585303d153f13bc4c1bf678
-  data.tar.gz: dae5536d6035f67546136f12ffe1fc52d602bdffc8dd5eeba120fec2313c4cd7
+  metadata.gz: 047f125ed11edef5fa998d90ff50d80f90879a065d6407b02184d21089f0b1a8
+  data.tar.gz: 1bb83c26b7aca89d6cce328298f51d9ba9c3e1e5b7fc1ea2adf3b59c88bf2c40
 SHA512:
-  metadata.gz: 48533967b1513900e0008f5046b138049fd60dd24fd0153ba69278c0f21e2e7183d4ef54380ae9f875f3f9a5853c09d4f57280c5c91a456c4aef560d5a0e9677
-  data.tar.gz: 8cf8d948c812075b068479e25737a0d43999831f2dea87a018d6d62fe8c1049d96bb27076f88173ed91d4bd4ae1939669d768402ee9e8ce8e5c215c14014d909
+  metadata.gz: '0847bf075101301c924d093b9561c6fe014efbd9bfbc94020427c0382ab38608c275f5e50e0df7221c21b21afc2282de920273bc22dbbb11db2822a367cabc8f'
+  data.tar.gz: 5b0bc3e6f05ffa239b0316c8927380eddfb322b5e207001930354f5482748f0b148bfd2a42b8796ae83fd19f0b7dd97d9f5b863fcc1500094406b7731bbf3c78

data/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+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.1.0] - 2026-01-13
+
+### Added
+- Initial release of rbtree-ruby gem
+- `RBTree` class: Pure Ruby Red-Black Tree implementation
+  - **Core operations**: `insert`, `delete`, `get` (aliased as `[]`/`[]=`) - O(log n)
+  - **Query methods**: `has_key?`, `empty?`, `size`, `min`, `max`
+  - **Iteration**: `each`, `reverse_each` with Enumerable support (`first`, `last`, `to_a`, etc.)
+  - **Stack operations**: `shift` (remove min), `pop` (remove max)
+  - **Range queries**: `lt`, `lte`, `gt`, `gte`, `between` - all support block iteration
+  - **Nearest search**: `nearest(key)` for finding closest numeric key
+  - **Utility**: `clear`, `inspect`, `valid?` (tree property validation)
+- `MultiRBTree` class: Red-Black Tree with multi-value support
+  - **Extends RBTree**: Inherits all range query and iteration methods
+  - **Multi-value storage**: Each key maps to a `RBTree::LinkedList` of values
+  - **Value retrieval**: `get` (first value), `get_all` (all values as LinkedList)
+  - **Flexible deletion**: `delete_one` (removes first value), `delete` (removes all values)
+  - **Order preservation**: Values maintain insertion order per key
+  - **Accurate sizing**: `size` reflects total key-value pairs, not unique keys
+- `RBTree::LinkedList` class: Internal doubly-linked list for MultiRBTree
+  - Supports `<<`, `shift`, `pop`, `first`, `last`, `empty?`, `each`, `reverse_each`
+  - Maintains insertion order with O(1) operations at both ends
+- Comprehensive RDoc documentation
+  - All 4 classes fully documented (RBTree, MultiRBTree, Node, LinkedList)
+  - 80%+ documentation coverage with type annotations
+  - Method signatures with `@param`, `@return`, `@yield` tags
+  - Practical usage examples for all public methods
+  - ASCII diagrams for tree rotation operations
+- MIT License (Copyright © 2026 Masahito Suzuki)
+
+[0.1.0]: https://github.com/firelzrd/rbtree-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Masahito Suzuki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,179 @@
+# RBTree
+
+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
+
+- **Self-Balancing Binary Search Tree**: Maintains optimal performance through red-black tree properties
+- **Ordered Operations**: Efficient range queries, min/max retrieval, and sorted iteration
+- **Multi-Value Support**: `MultiRBTree` class for storing multiple values per key
+- **Pure Ruby**: No C extensions required, works on any Ruby implementation
+- **Well-Documented**: Comprehensive RDoc documentation with examples
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rbtree-ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install rbtree-ruby
+```
+
+## Usage
+
+### Basic RBTree
+
+```ruby
+require 'rbtree'
+
+# Create an empty tree
+tree = RBTree.new
+
+# Or initialize with data
+tree = RBTree.new({3 => 'three', 1 => 'one', 2 => 'two'})
+tree = RBTree[[5, 'five'], [4, 'four']]
+
+# Insert and retrieve values
+tree.insert(10, 'ten')
+tree[20] = 'twenty'
+puts tree[10]  # => "ten"
+
+# Iterate in sorted order
+tree.each { |key, value| puts "#{key}: #{value}" }
+# Output:
+# 1: one
+# 2: two
+# 3: three
+# 10: ten
+# 20: twenty
+
+# Min and max
+tree.min  # => [1, "one"]
+tree.max  # => [20, "twenty"]
+
+# Range queries
+tree.lt(10)   # => [[1, "one"], [2, "two"], [3, "three"]]
+tree.gte(10)  # => [[10, "ten"], [20, "twenty"]]
+tree.between(2, 10)  # => [[2, "two"], [3, "three"], [10, "ten"]]
+
+# Shift and pop
+tree.shift  # => [1, "one"] (removes minimum)
+tree.pop    # => [20, "twenty"] (removes maximum)
+
+# Delete
+tree.delete(3)  # => "three"
+
+# Check membership
+tree.has_key?(2)  # => true
+tree.size         # => 2
+```
+
+### MultiRBTree with Duplicate Keys
+
+```ruby
+require 'rbtree'
+
+tree = MultiRBTree.new
+
+# Insert multiple values for the same key
+tree.insert(1, 'first one')
+tree.insert(1, 'second one')
+tree.insert(1, 'third one')
+tree.insert(2, 'two')
+
+tree.size  # => 4 (total number of key-value pairs)
+
+# Get first value
+tree.get(1)      # => "first one"
+tree[1]          # => "first one"
+
+# Get all values for a key
+tree.get_all(1)  # => LinkedList with ["first one", "second one", "third one"]
+
+# Iterate over all key-value pairs
+tree.each { |k, v| puts "#{k}: #{v}" }
+# Output:
+# 1: first one
+# 1: second one
+# 1: third one
+# 2: two
+
+# Delete only first value
+tree.delete_one(1)  # => "first one"
+tree.get(1)         # => "second one"
+
+# Delete all values for a key
+tree.delete(1)      # removes all remaining values
+```
+
+### Nearest Key Search
+
+```ruby
+tree = RBTree.new({1 => 'one', 5 => 'five', 10 => 'ten'})
+
+tree.nearest(4)   # => [5, "five"]  (closest key to 4)
+tree.nearest(7)   # => [5, "five"]  (same distance, returns smaller key)
+tree.nearest(8)   # => [10, "ten"]
+```
+
+## Performance
+
+All major operations run in **O(log n)** time:
+
+- `insert(key, value)` - O(log n)
+- `delete(key)` - O(log n)
+- `get(key)` / `[]` - O(log n)
+- `min` / `max` - O(1) for min, O(log n) for max
+- `shift` / `pop` - O(log n)
+
+Iteration over all elements takes O(n) time.
+
+## API Documentation
+
+Full RDoc documentation is available. Generate it locally with:
+
+```bash
+rdoc lib/rbtree.rb
+```
+
+Then open `doc/index.html` in your browser.
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies.can then run:
+
+```bash
+# Generate RDoc documentation
+rake rdoc
+
+# Build the gem
+rake build
+
+# Install locally
+rake install
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/firelzrd/rbtree-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Author
+
+Masahito Suzuki (firelzrd@gmail.com)
+
+Copyright © 2026 Masahito Suzuki

data/Rakefile

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "doc"
+  rdoc.title    = "RBTree Documentation"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("lib/**/*.rb")
+  rdoc.rdoc_files.include("README.md")
+  rdoc.rdoc_files.include("LICENSE")
+end
+
+desc "Build the gem"
+task :build do
+  sh "gem build rbtree-ruby.gemspec"
+end
+
+desc "Install the gem locally"
+task :install => :build do
+  sh "gem install ./rbtree-ruby-#{RBTree::VERSION}.gem"
+end
+
+desc "Clean build artifacts"
+task :clean do
+  sh "rm -f *.gem"
+  sh "rm -rf doc/"
+end
+
+task :default => :rdoc

data/lib/rbtree/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class RBTree
+  # The version of the rbtree-ruby gem
+  VERSION = "0.1.1"
+end