ruby_binary_search 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e8f5f86b8bbbf1618e3d795de3f817bb753372c7f24005301385f7da40c720ea
+  data.tar.gz: 433b0100900bf1bd1846d10e785acf63c83505adfc91d5424f783360eb8504fd
+SHA512:
+  metadata.gz: f3e41db0b009ae95f1f3ac5b12018a6df9f475ef7d483a5ba395a26c32a2f0a301297b5b12ee4815a803fc26ee25a3b6709fc3466a8b677082723e90e260569c
+  data.tar.gz: 5eb34f6900de0ffc7681d5a50989abf6182de46b93342f234f63716c1cabbcc7b2f58cf74bb67a5bd6de5ac9eacbb0cb002d514abca66b45a094e8efec765992

data/.rspec

@@ -0,0 +1,3 @@
+--format progress
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+inherit_gem:
+  rubocop-rails_config:
+    - config/rails.yml
+
+Style/ClassAndModuleChildren:
+  EnforcedStyle: nested
+
+Lint/Debugger:
+  Enabled: true
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: single_quotes

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-07-18
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 sebi
+
+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,104 @@
+# BinarySearch 🌳🔍
+
+Welcome to BinarySearch, a gem that brings the power of Red-Black Trees to your Ruby projects! 🚀
+
+## What is BinarySearch? 🤔
+
+BinarySearch is a Ruby gem that implements a self-balancing binary search tree using the Red-Black Tree algorithm. It provides a list-like interface with blazing-fast search, insertion, and deletion operations. 💨
+
+## Why BinarySearch? 🌟
+
+- **Efficiency**: Operations like search, insert, and delete are O(log n), making it much faster than standard arrays for large datasets. 📈
+- **Self-balancing**: The Red-Black Tree ensures that the tree remains balanced, maintaining consistent performance even with frequent modifications. ⚖️
+- **Sorted storage**: Elements are always stored in sorted order, making it perfect for applications that require sorted data. 📊
+- **Flexible**: Supports common list operations like push, pop, shift, and unshift, as well as set operations like union and intersection. 🛠️
+
+## Installation 💻
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'binary_search'
+```
+
+And then execute:
+```bash
+bundle install
+```
+
+## Usage 🚀
+Here's a quick example of how to use BinarySearch:
+
+```ruby
+require 'binary_search'
+
+# Create a new list
+list = BinarySearch::List.new([3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5])
+
+# Get the sorted array
+puts list.to_a  # Output: [1, 1, 2, 3, 3, 4, 5, 5, 5, 6, 9]
+
+# Check if a value exists
+puts list.include?(4)  # Output: true
+
+# Remove all instances of a value
+list.delete(1)
+puts list.to_a  # Output: [2, 3, 3, 4, 5, 5, 5, 6, 9]
+
+# Add a new value
+list.insert(7)
+puts list.to_a  # Output: [2, 3, 3, 4, 5, 5, 5, 6, 7, 9]
+
+# Get the minimum and maximum values
+puts list.min  # Output: 2
+puts list.max  # Output: 9
+```
+Custom objects
+```ruby
+require 'binary_search'
+class Person
+  attr_accessor :name, :age
+
+  def initialize(name, age)
+    @name = name
+    @age = age
+  end
+
+  def <=>(other)
+    @age <=> other.age
+  end
+end
+
+
+list = BinarySearch::List.new([
+  Person.new('Alice', 25),
+  Person.new('Bob', 30),
+  Person.new('Charlie', 20),
+  Person.new('David', 35)
+])
+
+puts list.to_a.map(&:name)  # Output: ["Charlie", "Alice", "Bob", "David"]
+```
+
+## Why is BinarySearch better than normal search? 🏆
+
+- Speed: For large datasets, binary search is significantly faster than linear search. While a normal array search takes O(n) time, BinarySearch takes only O(log n) time. 🐇
+- Always sorted: The list is always maintained in sorted order, which is useful for many applications and algorithms. 📑
+- Efficient insertions and deletions: Unlike normal arrays where insertions and deletions can be O(n) operations, BinarySearch performs these in O(log n) time. 🔄
+- Memory efficiency: Red-Black Trees are more memory-efficient than hash tables for certain types of data and operations. 💾
+- Range queries: BinarySearch makes it easy to perform range queries efficiently, which can be cumbersome with normal arrays. 🎯
+
+## Development 🛠️
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing 🤝
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/sebyx07/binary_search. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.
+
+## License 📄
+The gem is available as open source under the terms of the MIT License.
+
+## Code of Conduct 🤓
+Everyone interacting in the BinarySearch project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lefthook.yml

@@ -0,0 +1,8 @@
+pre-commit:
+  commands:
+    rubocop:
+      run: bundle exec rubocop -A
+      skip:
+        - merge
+        - rebase
+      stage_fixed: true

data/lib/binary_search/list.rb

@@ -0,0 +1,526 @@
+# frozen_string_literal: true
+
+module BinarySearch
+  # A self-balancing binary search tree implementation of a list
+  #
+  # This class provides a list-like interface backed by a Red-Black Tree,
+  # which ensures O(log n) time complexity for most operations.
+  #
+  # @example Creating and using a BinarySearch::List
+  #   list = BinarySearch::List.new([3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5])
+  #   list.to_a  # => [1, 1, 2, 3, 3, 4, 5, 5, 5, 6, 9]
+  #   list.include?(4)  # => true
+  #   list.delete(1)  # Removes all instances of 1
+  #   list.to_a  # => [2, 3, 3, 4, 5, 5, 5, 6, 9]
+  class List
+    include Enumerable
+
+    # Initialize a new BinarySearch::List
+    #
+    # @param from [Array] An array to initialize the list with
+    #
+    # @example Create an empty list
+    #   list = BinarySearch::List.new
+    #
+    # @example Create a list from an array
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    def initialize(from = [])
+      @tree = BinarySearch::RedBlackTree.new
+      build_tree(from)
+    end
+
+    # Insert a value into the list
+    #
+    # This method inserts a value into the list, maintaining the sorted order.
+    # It has a time complexity of O(log n).
+    #
+    # @param value [Object] The value to insert
+    # @return [BinarySearch::List] The list object (for method chaining)
+    #
+    # @example Insert a value
+    #   list.insert(4)  # => #<BinarySearch::List: ...>
+    #   list << 5  # => #<BinarySearch::List: ...>
+    def insert(value)
+      @tree.insert(value)
+      @size = nil
+      self
+    end
+    alias_method :append, :insert
+    alias_method :push, :insert
+    alias_method :<<, :insert
+
+    # Delete all occurrences of a value from the list
+    #
+    # This method removes all instances of the specified value from the list.
+    # It has a time complexity of O(log n) for each deletion.
+    #
+    # @param value [Object] The value to delete
+    # @return [Boolean] True if any elements were deleted, false otherwise
+    #
+    # @example Delete a value
+    #   list = BinarySearch::List.new([1, 2, 2, 3, 4])
+    #   list.delete(2)  # => true
+    #   list.to_a  # => [1, 3, 4]
+    def delete(value)
+      deleted = false
+      while @tree.find(value)
+        @tree.remove(value)
+        @size -= 1 if @size
+        deleted = true
+      end
+      deleted
+    end
+
+    # Check if a value is in the list
+    #
+    # This method checks if the list contains the specified value.
+    # It has a time complexity of O(log n).
+    #
+    # @param value [Object] The value to check for
+    # @return [Boolean] True if the value is in the list, false otherwise
+    #
+    # @example Check for a value
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list.include?(3)  # => true
+    #   list.include?(6)  # => false
+    def include?(value)
+      !@tree.find(value).nil?
+    end
+
+    # Convert the list to an array
+    #
+    # This method returns an array representation of the list in sorted order.
+    # It has a time complexity of O(n).
+    #
+    # @return [Array] An array representation of the list
+    #
+    # @example Convert to array
+    #   list = BinarySearch::List.new([3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5])
+    #   list.to_a  # => [1, 1, 2, 3, 3, 4, 5, 5, 5, 6, 9]
+    def to_a
+      inorder_traversal(@tree.root)
+    end
+
+    # Get the size of the list
+    #
+    # This method returns the number of elements in the list.
+    # It has a time complexity of O(1) if the size is cached, or O(n) otherwise.
+    #
+    # @return [Integer] The number of elements in the list
+    #
+    # @example Get the size
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list.size  # => 5
+    def size
+      @size ||= inorder_traversal(@tree.root).size
+    end
+
+    # Check if the list is empty
+    #
+    # This method checks if the list contains no elements.
+    # It has a time complexity of O(1).
+    #
+    # @return [Boolean] True if the list is empty, false otherwise
+    #
+    # @example Check if empty
+    #   list = BinarySearch::List.new
+    #   list.empty?  # => true
+    #   list.insert(1)
+    #   list.empty?  # => false
+    def empty?
+      @tree.root.nil?
+    end
+
+    # Access elements by index or range
+    #
+    # This method allows accessing elements by index or range, similar to Array.
+    # It has a time complexity of O(n) in the worst case.
+    #
+    # @param arg [Integer, Range] The index or range to access
+    # @return [Object, BinarySearch::List, nil] The element(s) at the given index or range, or nil if out of bounds
+    # @raise [ArgumentError] If the argument is not an Integer or Range
+    #
+    # @example Access by index
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list[2]  # => 3
+    #
+    # @example Access by range
+    #   list[1..3]  # => #<BinarySearch::List: [2, 3, 4]>
+    def [](arg)
+      case arg
+      when Integer
+        return nil if arg < 0 || arg >= size
+        to_a[arg]
+      when Range
+        start = arg.begin
+        finish = arg.end
+        start = size + start if start < 0
+        finish = size + finish if finish < 0
+        finish -= 1 if arg.exclude_end?
+
+        return nil if start < 0 || start >= size
+
+        result = []
+        (start..finish).each do |i|
+          break if i >= size
+          result << to_a[i]
+        end
+        self.class.new(result)
+      else
+        raise ArgumentError, "Invalid argument type: #{arg.class}"
+      end
+    end
+
+    # Iterate over each element in the list
+    #
+    # This method yields each element in the list to the given block.
+    # It has a time complexity of O(n).
+    #
+    # @yield [Object] Gives each element in the list to the block
+    # @return [Enumerator] If no block is given
+    #
+    # @example Iterate over elements
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list.each { |x| puts x }  # Prints each number on a new line
+    def each(&block)
+      to_a.each(&block)
+    end
+
+    # Clear all elements from the list
+    #
+    # This method removes all elements from the list, leaving it empty.
+    # It has a time complexity of O(1).
+    #
+    # @return [BinarySearch::List] The empty list object
+    #
+    # @example Clear the list
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list.clear  # => #<BinarySearch::List: []>
+    #   list.empty?  # => true
+    def clear
+      @tree = BinarySearch::RedBlackTree.new
+      @size = 0
+      self
+    end
+
+    # Get the first element in the list
+    #
+    # This method returns the smallest element in the list.
+    # It has a time complexity of O(log n).
+    #
+    # @return [Object, nil] The first element, or nil if the list is empty
+    #
+    # @example Get the first element
+    #   list = BinarySearch::List.new([3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5])
+    #   list.first  # => 1
+    def first
+      return nil if empty?
+      leftmost_node(@tree.root).key
+    end
+
+    # Get the last element in the list
+    #
+    # This method returns the largest element in the list.
+    # It has a time complexity of O(log n).
+    #
+    # @return [Object, nil] The last element, or nil if the list is empty
+    #
+    # @example Get the last element
+    #   list = BinarySearch::List.new([3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5])
+    #   list.last  # => 9
+    def last
+      return nil if empty?
+      rightmost_node(@tree.root).key
+    end
+
+    # Remove and return the last element in the list
+    #
+    # This method removes and returns the largest element in the list.
+    # It has a time complexity of O(log n).
+    #
+    # @return [Object, nil] The last element, or nil if the list is empty
+    #
+    # @example Remove the last element
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list.pop  # => 5
+    #   list.to_a  # => [1, 2, 3, 4]
+    def pop
+      return nil if empty?
+      last_value = last
+      @tree.remove(last_value)
+      @size -= 1 if @size
+      last_value
+    end
+
+    # Remove and return the first element in the list
+    #
+    # This method removes and returns the smallest element in the list.
+    # It has a time complexity of O(log n).
+    #
+    # @return [Object, nil] The first element, or nil if the list is empty
+    #
+    # @example Remove the first element
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list.shift  # => 1
+    #   list.to_a  # => [2, 3, 4, 5]
+    def shift
+      return nil if empty?
+      first_value = first
+      @tree.remove(first_value)
+      @size -= 1 if @size
+      first_value
+    end
+
+    # Insert a value at the beginning of the list
+    #
+    # This method inserts a value at the beginning of the list.
+    # It has a time complexity of O(log n).
+    #
+    # @param value [Object] The value to insert
+    # @return [BinarySearch::List] The list object (for method chaining)
+    #
+    # @example Insert at the beginning
+    #   list = BinarySearch::List.new([2, 3, 4, 5])
+    #   list.unshift(1)  # => #<BinarySearch::List: [1, 2, 3, 4, 5]>
+    def unshift(value)
+      insert(value)
+      self
+    end
+
+    # Get the maximum value in the list
+    #
+    # This method returns the largest element in the list.
+    # It has a time complexity of O(log n).
+    #
+    # @return [Object, nil] The maximum value, or nil if the list is empty
+    #
+    # @example Get the maximum value
+    #   list = BinarySearch::List.new([3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5])
+    #   list.max  # => 9
+    def max
+      last
+    end
+
+    # Get the minimum value in the list
+    #
+    # This method returns the smallest element in the list.
+    # It has a time complexity of O(log n).
+    #
+    # @return [Object, nil] The minimum value, or nil if the list is empty
+    #
+    # @example Get the minimum value
+    #   list = BinarySearch::List.new([3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5])
+    #   list.min  # => 1
+    def min
+      first
+    end
+
+    # Calculate the sum of all elements in the list
+    #
+    # This method returns the sum of all elements in the list.
+    # It has a time complexity of O(n).
+    #
+    # @return [Numeric] The sum of all elements
+    #
+    # @example Calculate the sum
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list.sum  # => 15
+    def sum
+      to_a.sum
+    end
+
+    # Find the first element that satisfies the given condition
+    #
+    # This method returns the first element for which the given block returns true.
+    # It has a time complexity of O(n) in the worst case.
+    #
+    # @yield [Object] Gives each element to the block
+    # @return [Object, nil] The first element for which the block returns true, or nil if none found
+    #
+    # @example Find an element
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list.find { |x| x > 3 }  # => 4
+    def find
+      each { |element| return element if yield(element) }
+      nil
+    end
+
+    # Create a new list with duplicate elements removed
+    #
+    # This method returns a new list with all duplicate elements removed.
+    # It has a time complexity of O(n log n).
+    #
+    # @return [BinarySearch::List] A new list with unique elements
+    #
+    # @example Remove duplicates
+    #   list = BinarySearch::List.new([1, 2, 2, 3, 3, 3, 4, 5])
+    #   list.uniq.to_a  # => [1, 2, 3, 4, 5]
+    def uniq
+      self.class.new(to_a.uniq)
+    end
+
+    # Concatenate two lists
+    #
+    # This method returns a new list containing all elements from both lists.
+    # It has a time complexity of O(n + m), where n and m are the sizes of the lists.
+    #
+    # @param other [BinarySearch::List] The list to concatenate
+    # @return [BinarySearch::List] A new list containing elements from both lists
+    #
+    # @example Concatenate lists
+    #   list1 = BinarySearch::List.new([1, 2, 3])
+    #   list2 = BinarySearch::List.new([4, 5, 6])
+    #   (list1 + list2).to_a  # => [1, 2, 3, 4, 5, 6]
+    def +(other)
+      self.class.new(to_a + other.to_a)
+    end
+
+    # Compute the difference between two lists
+    #
+    # This method returns a new list containing elements that are in the current list
+    # but not in the other list, taking into account the number of occurrences of each element.
+    # It has a time complexity of O(n log n + m log m), where n and m are the sizes of the lists.
+    #
+    # @param other [BinarySearch::List] The list to subtract
+    # @return [BinarySearch::List] A new list containing elements in this list but not in the other
+    #
+    # @example Compute the difference
+    #   list1 = BinarySearch::List.new([1, 2, 2, 3, 4, 5])
+    #   list2 = BinarySearch::List.new([2, 4, 6])
+    #   (list1 - list2).to_a  # => [1, 2, 3, 5]
+    def -(other)
+      result = self.class.new
+      self_counts = Hash.new(0)
+      other_counts = Hash.new(0)
+
+      self.each { |item| self_counts[item] += 1 }
+      other.each { |item| other_counts[item] += 1 }
+
+      self_counts.each do |item, count|
+        diff = count - other_counts[item]
+        diff.times { result.insert(item) } if diff > 0
+      end
+
+      result
+    end
+
+    # Compute the intersection of two lists
+    #
+    # This method returns a new list containing elements common to both lists,
+    # taking into account the number of occurrences of each element.
+    # It has a time complexity of O(n log n + m log m), where n and m are the sizes of the lists.
+    #
+    # @param other [BinarySearch::List] The list to intersect with
+    # @return [BinarySearch::List] A new list containing elements common to both lists
+    #
+    # @example Compute the intersection
+    #   list1 = BinarySearch::List.new([1, 2, 2, 3, 4, 5])
+    #   list2 = BinarySearch::List.new([2, 2, 4, 6])
+    #   (list1 & list2).to_a  # => [2, 2, 4]
+    def &(other)
+      self.class.new(to_a & other.to_a)
+    end
+
+    # Compute the union of two lists
+    #
+    # This method returns a new list containing unique elements from both lists.
+    # It has a time complexity of O(n log n + m log m), where n and m are the sizes of the lists.
+    #
+    # @param other [BinarySearch::List] The list to unite with
+    # @return [BinarySearch::List] A new list containing unique elements from both lists
+    #
+    # @example Compute the union
+    #   list1 = BinarySearch::List.new([1, 2, 3, 4])
+    #   list2 = BinarySearch::List.new([3, 4, 5, 6])
+    #   (list1 | list2).to_a  # => [1, 2, 3, 4, 5, 6]
+    def |(other)
+      self.class.new(to_a | other.to_a)
+    end
+
+    # Compare two lists for equality
+    #
+    # This method checks if two lists have the same elements in the same order.
+    # It has a time complexity of O(n), where n is the size of the lists.
+    #
+    # @param other [Object] The object to compare with
+    # @return [Boolean] True if the lists are equal, false otherwise
+    #
+    # @example Compare lists
+    #   list1 = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list2 = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list3 = BinarySearch::List.new([5, 4, 3, 2, 1])
+    #   list1 == list2  # => true
+    #   list1 == list3  # => false
+    def ==(other)
+      return false unless other.is_a?(BinarySearch::List)
+      return true if self.equal?(other)
+      self.to_a == other.to_a
+    end
+
+    # Provide a string representation of the list
+    #
+    # This method returns a concise string representation of the list,
+    # showing the class name and the size of the list.
+    #
+    # @return [String] A string representation of the list
+    #
+    # @example Inspect the list
+    #   list = BinarySearch::List.new([1, 2, 3, 4, 5])
+    #   list.inspect  # => "#<BinarySearch::List: (5 elements)>"
+    def inspect
+      "#<#{self.class}: (#{size} elements)>"
+    end
+
+    private
+      # Build the tree from an initial list
+      #
+      # This method inserts each element from the initial list into the tree.
+      # It has a time complexity of O(n log n), where n is the size of the initial list.
+      #
+      # @param list [Array] The initial list of elements
+      # @return [void]
+      def build_tree(list)
+        list.each { |item| @tree.insert(item) }
+        @size = list.size
+      end
+
+      # Perform an inorder traversal of the tree
+      #
+      # This method traverses the tree in-order and returns an array of the elements.
+      # It has a time complexity of O(n), where n is the number of nodes in the tree.
+      #
+      # @param node [BinarySearch::RedBlackTree::Node] The current node
+      # @param result [Array] The result array
+      # @return [Array] An array of elements in sorted order
+      def inorder_traversal(node, result = [])
+        return result if node.nil?
+        inorder_traversal(node.left, result)
+        result << node.key
+        inorder_traversal(node.right, result)
+      end
+
+      # Find the leftmost node in a subtree
+      #
+      # This method finds the node with the smallest key in the given subtree.
+      # It has a time complexity of O(log n) in a balanced tree.
+      #
+      # @param node [BinarySearch::RedBlackTree::Node] The root of the subtree
+      # @return [BinarySearch::RedBlackTree::Node] The leftmost node
+      def leftmost_node(node)
+        return node if node.left.nil?
+        leftmost_node(node.left)
+      end
+
+      # Find the rightmost node in a subtree
+      #
+      # This method finds the node with the largest key in the given subtree.
+      # It has a time complexity of O(log n) in a balanced tree.
+      #
+      # @param node [BinarySearch::RedBlackTree::Node] The root of the subtree
+      # @return [BinarySearch::RedBlackTree::Node] The rightmost node
+      def rightmost_node(node)
+        return node if node.right.nil?
+        rightmost_node(node.right)
+      end
+  end
+end

data/lib/binary_search/red_black_tree/node.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BinarySearch
+  class RedBlackTree
+    # Represents a node in the Red-Black Tree
+    #
+    # A node contains a key, color, references to its left and right children,
+    # and a reference to its parent. The color is used to maintain the balance
+    # properties of the Red-Black Tree.
+    Node = Struct.new('Node', :key, :color, :left, :right, :parent) do
+      # Creates a new Node
+      #
+      # @param key [Comparable] The key stored in the node
+      # @param color [Symbol] The color of the node (:red or :black)
+      # @param left [Node, nil] The left child of the node
+      # @param right [Node, nil] The right child of the node
+      # @param parent [Node, nil] The parent of the node
+      def initialize(key, color = :red, left = nil, right = nil, parent = nil)
+        super(key, color, left, right, parent)
+      end
+
+      # Checks if the node is black
+      #
+      # @return [Boolean] true if the node is black, false otherwise
+      def black?
+        color == :black
+      end
+
+      # Checks if the node is red
+      #
+      # @return [Boolean] true if the node is red, false otherwise
+      def red?
+        color == :red
+      end
+    end
+  end
+end

data/lib/binary_search/red_black_tree.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+module BinarySearch
+  # Implements a Red-Black Tree, a self-balancing binary search tree
+  #
+  # A Red-Black Tree is a type of self-balancing binary search tree that maintains
+  # balance through the use of node colors (red and black) and a set of properties:
+  #
+  # 1. Every node is either red or black.
+  # 2. The root is black.
+  # 3. Every leaf (NIL) is black.
+  # 4. If a node is red, then both its children are black.
+  # 5. For each node, all simple paths from the node to descendant leaves contain the
+  #    same number of black nodes.
+  #
+  # These properties ensure that the tree remains approximately balanced during
+  # insertions and deletions, guaranteeing O(log n) time complexity for basic
+  # operations like search, insert, and delete.
+  class RedBlackTree
+    # @return [Node, nil] The root node of the tree
+    attr_reader :root
+
+    # Initializes an empty Red-Black Tree
+    def initialize
+      @root = nil
+    end
+
+    # Inserts a new key into the tree
+    #
+    # The insertion process involves:
+    # 1. Performing a standard BST insertion
+    # 2. Coloring the new node red
+    # 3. Rebalancing the tree to maintain Red-Black properties
+    #
+    # @param key [Comparable] The key to insert
+    # @return [void]
+    def insert(key)
+      new_node = Node.new(key)
+      if @root.nil?
+        @root = new_node
+        @root.color = :black
+      else
+        current = @root
+        parent = nil
+        while current
+          parent = current
+          comparison = key <=> current.key
+          case comparison
+          when -1
+            current = current.left
+          when 1
+            current = current.right
+          else
+            # For duplicates, we'll add to the right
+            current = current.right
+          end
+        end
+        new_node.parent = parent
+        comparison = key <=> parent.key
+        if comparison <= 0
+          parent.left = new_node
+        else
+          parent.right = new_node
+        end
+        fix_insert(new_node)
+      end
+    end
+
+    # Removes a key from the tree
+    #
+    # The removal process involves:
+    # 1. Finding the node to be removed
+    # 2. If the node has two children, replacing it with its successor
+    # 3. Removing the node (or its successor)
+    # 4. Rebalancing the tree if the removed node was black
+    #
+    # @param key [Comparable] The key to remove
+    # @return [Node, nil] The removed node, or nil if the key was not found
+    def remove(key)
+      node = find(key)
+      return nil unless node
+
+      remove_node(node)
+    end
+
+    # Updates a key in the tree
+    #
+    # This operation ensures that the tree structure remains valid after updating a key.
+    # It's implemented as a removal of the old key followed by an insertion of the new key.
+    #
+    # @param old_key [Comparable] The key to update
+    # @param new_key [Comparable] The new key value
+    # @return [Boolean, nil] true if updated, false if new_key already exists, nil if old_key not found
+    def update(old_key, new_key)
+      node = find(old_key)
+      return nil unless node
+      return false if find(new_key)
+
+      node.key = new_key
+      true
+    end
+
+    # Finds a node with the given key
+    #
+    # This method performs a standard binary search tree lookup.
+    #
+    # @param key [Comparable] The key to find
+    # @return [Node, nil] The node with the given key, or nil if not found
+    def find(key)
+      current = @root
+      while current
+        comparison = key <=> current.key
+        return current if comparison == 0
+        current = comparison < 0 ? current.left : current.right
+      end
+      nil
+    end
+
+    private
+      # Fixes the tree after insertion to maintain Red-Black properties
+      #
+      # This method is called after every insertion to ensure that the Red-Black
+      # properties are maintained. It performs color changes and rotations as necessary.
+      #
+      # @param node [Node] The newly inserted node
+      # @return [void]
+      def fix_insert(node)
+        while node.parent&.red?
+          if node.parent == node.parent.parent&.left
+            uncle = node.parent.parent&.right
+            if uncle&.red?
+              node.parent.color = :black
+              uncle.color = :black
+              node.parent.parent.color = :red
+              node = node.parent.parent
+            else
+              if node == node.parent.right
+                node = node.parent
+                left_rotate(node)
+              end
+              node.parent.color = :black
+              node.parent.parent.color = :red
+              right_rotate(node.parent.parent)
+            end
+          else
+            uncle = node.parent.parent&.left
+            if uncle&.red?
+              node.parent.color = :black
+              uncle.color = :black
+              node.parent.parent.color = :red
+              node = node.parent.parent
+            else
+              if node == node.parent.left
+                node = node.parent
+                right_rotate(node)
+              end
+              node.parent.color = :black
+              node.parent.parent.color = :red
+              left_rotate(node.parent.parent)
+            end
+          end
+        end
+        @root.color = :black
+      end
+
+      # Performs a left rotation on the given node
+      #
+      # A left rotation is a local operation in a search tree that changes the structure
+      # of the tree while preserving the search tree properties of the nodes involved.
+      #
+      # @param x [Node] The node to rotate
+      # @return [void]
+      def left_rotate(x)
+        y = x.right
+        x.right = y.left
+        y.left.parent = x if y.left
+        y.parent = x.parent
+        if x.parent.nil?
+          @root = y
+        elsif x == x.parent.left
+          x.parent.left = y
+        else
+          x.parent.right = y
+        end
+        y.left = x
+        x.parent = y
+      end
+
+      # Performs a right rotation on the given node
+      #
+      # A right rotation is the mirror operation of a left rotation.
+      #
+      # @param y [Node] The node to rotate
+      # @return [void]
+      def right_rotate(y)
+        x = y.left
+        y.left = x.right
+        x.right.parent = y if x.right
+        x.parent = y.parent
+        if y.parent.nil?
+          @root = x
+        elsif y == y.parent.right
+          y.parent.right = x
+        else
+          y.parent.left = x
+        end
+        x.right = y
+        y.parent = x
+      end
+
+      # Removes a node from the tree
+      #
+      # This method handles the actual removal of a node and calls the necessary
+      # fix-up routines to maintain the Red-Black properties.
+      #
+      # @param node [Node] The node to remove
+      # @return [void]
+      def remove_node(node)
+        if node.left && node.right
+          successor = minimum(node.right)
+          node.key = successor.key
+          remove_node(successor)
+        else
+          child = node.left || node.right
+          if node.black?
+            if child&.red?
+              child.color = :black
+            else
+              delete_case1(node)
+            end
+          end
+          replace_node(node, child)
+        end
+        @root.color = :black if @root
+      end
+
+      # Finds the minimum node in a subtree
+      #
+      # This method is used in the deletion process to find the successor of a node.
+      #
+      # @param node [Node] The root of the subtree
+      # @return [Node] The minimum node
+      def minimum(node)
+        node = node.left while node.left
+        node
+      end
+
+      # Replaces one node with another in the tree
+      #
+      # This method is a helper for the removal process, updating the necessary
+      # parent-child relationships.
+      #
+      # @param old [Node] The node to be replaced
+      # @param new [Node, nil] The replacement node
+      # @return [void]
+      def replace_node(old, new)
+        if old.parent.nil?
+          @root = new
+        elsif old == old.parent.left
+          old.parent.left = new
+        else
+          old.parent.right = new
+        end
+        new.parent = old.parent if new
+      end
+
+      # Handles case 1 of the delete fixup
+      #
+      # The delete fixup cases are part of the algorithm to maintain Red-Black
+      # properties after a black node is removed from the tree.
+      #
+      # @param node [Node] The node being processed
+      # @return [void]
+      def delete_case1(node)
+        delete_case2(node) if node.parent
+      end
+
+      # Handles case 2 of the delete fixup
+      #
+      # @param node [Node] The node being processed
+      # @return [void]
+      def delete_case2(node)
+        sibling = get_sibling(node)
+        return if sibling.nil? || node.parent.nil?
+        if sibling.red?
+          node.parent.color = :red
+          sibling.color = :black
+          if node == node.parent.left
+            left_rotate(node.parent)
+          else
+            right_rotate(node.parent)
+          end
+        end
+        delete_case3(node)
+      end
+
+      # Handles case 3 of the delete fixup
+      #
+      # @param node [Node] The node being processed
+      # @return [void]
+      def delete_case3(node)
+        sibling = get_sibling(node)
+        return if sibling.nil? || node.parent.nil?
+        if node.parent.black? && sibling.black? &&
+          (!sibling.left || sibling.left.black?) &&
+          (!sibling.right || sibling.right.black?)
+          sibling.color = :red
+          delete_case1(node.parent)
+        else
+          delete_case4(node)
+        end
+      end
+
+      # Handles case 4 of the delete fixup
+      #
+      # @param node [Node] The node being processed
+      # @return [void]
+      def delete_case4(node)
+        sibling = get_sibling(node)
+        return if sibling.nil? || node.parent.nil?
+        if node.parent.red? && sibling.black? &&
+          (!sibling.left || sibling.left.black?) &&
+          (!sibling.right || sibling.right.black?)
+          sibling.color = :red
+          node.parent.color = :black
+        else
+          delete_case5(node)
+        end
+      end
+
+      # Handles case 5 of the delete fixup
+      #
+      # @param node [Node] The node being processed
+      # @return [void]
+      def delete_case5(node)
+        sibling = get_sibling(node)
+        return if sibling.nil? || node.parent.nil?
+        if sibling.black?
+          if node == node.parent.left &&
+            (!sibling.right || sibling.right.black?) &&
+            sibling.left&.red?
+            sibling.color = :red
+            sibling.left.color = :black
+            right_rotate(sibling)
+          elsif node == node.parent.right &&
+            (!sibling.left || sibling.left.black?) &&
+            sibling.right&.red?
+            sibling.color = :red
+            sibling.right.color = :black
+            left_rotate(sibling)
+          end
+        end
+        delete_case6(node)
+      end
+
+      # Handles case 6 of the delete fixup
+      #
+      # @param node [Node] The node being processed
+      # @return [void]
+      def delete_case6(node)
+        sibling = get_sibling(node)
+        return if sibling.nil? || node.parent.nil?
+        sibling.color = node.parent.color
+        node.parent.color = :black
+        if node == node.parent.left
+          sibling.right.color = :black if sibling.right
+          left_rotate(node.parent)
+        else
+          sibling.left.color = :black if sibling.left
+          right_rotate(node.parent)
+        end
+      end
+
+      # Gets the sibling of a node
+      #
+      # This helper method is used in the delete fixup process.
+      #
+      # @param node [Node] The node whose sibling to find
+      # @return [Node, nil] The sibling node, or nil if there is no sibling
+      def get_sibling(node)
+        return nil if node.parent.nil?
+        node == node.parent.left ? node.parent.right : node.parent.left
+      end
+  end
+end

data/lib/binary_search/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module BinarySearch
+  VERSION = '1.0.0'
+end

data/lib/ruby_binary_search.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'singleton'
+
+Dir[File.join(__dir__, 'binary_search', '**', '*.rb')].each { |file| require file }
+
+module BinarySearch
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: ruby_binary_search
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- sebi
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2024-08-03 00:00:00.000000000 Z
+dependencies: []
+description: Binary search list implemented in ruby using red-black self-balancing
+  tree
+email:
+- gore.sebyx@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lefthook.yml
+- lib/binary_search/list.rb
+- lib/binary_search/red_black_tree.rb
+- lib/binary_search/red_black_tree/node.rb
+- lib/binary_search/version.rb
+- lib/ruby_binary_search.rb
+homepage: https://github.com/sebyx07/ruby-binary-search
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/sebyx07/ruby-binary-search
+  source_code_uri: https://github.com/sebyx07/ruby-binary-search
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key: 
+specification_version: 4
+summary: Binary search list implemented in ruby using red-black self-balancing tree
+test_files: []