veb_tree 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e23be52707f931f14be4a781a5b3772bc222c23c3843c59313b074fd64eb2e9c
+  data.tar.gz: 626f915e7d226ae97e08b6d8c448326716d3cbc12f88a2af37ba7e62c65b9d81
+SHA512:
+  metadata.gz: b90a39d5c9480a9b1ac3174b1d078421634cd70e361154c00599edf6906370c4250d2491ee69e166f1c149a45847ad910484e4b2fe9537c6d4f26cf9c74afe05
+  data.tar.gz: d8b9ee66e04ababef90de5f0cfe2f12c2d1da3bbc6146b97899219dfc592bcba95c47293026bc798cb74e505c19f67b409c7640cd64b9aeecf1e3fad5737ab46

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] - 2025-01-XX
+
+### Added
+- Initial release of VebTree gem
+- Full Van Emde Boas tree implementation in C++17
+- Ruby bindings for all core operations
+- O(log log U) performance for insert, delete, search, successor, predecessor
+- O(1) performance for min/max queries
+- Lazy cluster allocation for memory efficiency
+- Enumerable support for iteration
+- Comprehensive test suite
+- Full API documentation
+
+### Features
+- `VebTree::Tree.new(universe_size)` - Constructor with automatic power-of-2 rounding
+- `#insert(key)` - Insert element
+- `#delete(key)` - Delete element
+- `#include?(key)` / `#member?(key)` - Membership test
+- `#min` / `#max` - Get minimum/maximum elements (O(1))
+- `#successor(key)` - Get next larger element
+- `#predecessor(key)` - Get next smaller element
+- `#size` - Get number of elements
+- `#empty?` - Check if tree is empty
+- `#clear` - Remove all elements
+- `#each` - Iterate over elements in sorted order
+- `#to_a` - Convert to sorted array
+
+### Platform Support
+- Ruby 2.7+ on Linux (GCC 7+, Clang 5+)
+- Ruby 2.7+ on macOS (Xcode Command Line Tools)
+- Ruby 2.7+ on Windows (MinGW-w64, MSVC 2017+)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 [Your Name]
+
+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,96 @@
+# VebTree - Van Emde Boas Tree
+
+A high-performance Van Emde Boas (vEB) tree implementation for Ruby with a C++ core, providing **O(log log U)** time complexity for integer set operations.
+
+## Features
+
+- **Blazing Fast**: O(log log U) operations for insert, delete, search, successor, and predecessor
+- **Native Performance**: Core algorithm implemented in C++17
+- **Simple API**: Clean, idiomatic Ruby interface
+- **Memory Efficient**: Lazy cluster allocation
+- **Battle Tested**: Comprehensive test suite
+
+## Installation
+
+### Requirements
+
+- Ruby 2.7 or higher
+- C++17 compatible compiler:
+  - **Linux**: GCC 7+ or Clang 5+
+  - **macOS**: Xcode Command Line Tools
+  - **Windows**: MinGW-w64 or MSVC 2017+
+
+### Install via RubyGems
+```bash
+gem install veb_tree
+```
+
+## Install from Source
+```
+git clone https://github.com/yourusername/veb_tree.git
+cd veb_tree
+bundle install
+rake compile
+rake test
+gem build veb_tree.gemspec
+gem install veb_tree-*.gem
+```
+
+### Quick Start
+```
+require 'veb_tree'
+
+# Create a tree with universe size (will round to next power of 2)
+tree = VebTree::Tree.new(1000)  # Actual size: 1024
+
+# Insert elements
+tree.insert(42)
+tree.insert(100)
+tree.insert(7)
+tree.insert(500)
+
+# Check membership - O(log log U)
+tree.include?(42)   # => true
+tree.include?(99)   # => false
+
+# Min/Max - O(1)
+tree.min  # => 7
+tree.max  # => 500
+
+# Successor/Predecessor - O(log log U)
+tree.successor(42)    # => 100
+tree.predecessor(100) # => 42
+
+# Size and empty check
+tree.size     # => 4
+tree.empty?   # => false
+
+# Iterate in sorted order
+tree.each { |key| puts key }
+# Output: 7, 42, 100, 500
+
+# Convert to array
+tree.to_a  # => [7, 42, 100, 500]
+
+# Delete elements
+tree.delete(42)  # => true
+tree.delete(42)  # => false (not present)
+
+# Clear all elements
+tree.clear
+```
+
+### API Reference
+```VebTree::Tree.new(universe_size)```
+
+Creates a new Van Emde Boas tree.
+- universe_size (Integer): Maximum value that can be stored (exclusive). Will be 
+- rounded up to the next power of 2.
+- Returns: New VebTree::Tree instance
+- Raises: ArgumentError if universe_size is not positive
+
+#### Example
+```
+tree = VebTree::Tree.new(100)  # Actual universe: 128
+tree.universe_size  # => 128
+```

data/ext/veb_tree/extconf.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "mkmf"
+
+# Check for C++ compiler
+unless find_executable("g++") || find_executable("clang++")
+  abort "C++ compiler not found. Please install a C++ compiler."
+end
+
+# Set C++ compiler
+RbConfig::MAKEFILE_CONFIG["CXX"] = ENV["CXX"] || "g++"
+
+# C++17 standard
+$CXXFLAGS << " -std=c++17 -Wall -Wextra -O3"
+
+# Enable optimizations
+$CXXFLAGS << " -march=native" if ENV["NATIVE_ARCH"] == "1"
+
+# Debug flags if requested
+if ENV["DEBUG"] == "1"
+  $CXXFLAGS << " -g -O0 -DDEBUG"
+else
+  $CXXFLAGS << " -DNDEBUG"
+end
+
+# Platform-specific settings
+case RUBY_PLATFORM
+when /darwin/
+  # macOS specific flags
+  $CXXFLAGS << " -stdlib=libc++"
+when /linux/
+  # Linux specific flags
+  $LDFLAGS << " -lstdc++"
+when /mingw|mswin/
+  # Windows specific flags
+  $CXXFLAGS << " -static-libgcc -static-libstdc++"
+end
+
+# Create Makefile
+create_makefile("veb_tree/veb_tree")

data/ext/veb_tree/veb_tree_ext.cpp

@@ -0,0 +1,532 @@
+#include "veb_tree_ext.h"
+#include <algorithm>
+
+namespace VebTree {
+
+// ============================================================================
+// VEBTree Implementation
+// ============================================================================
+
+VEBTree::VEBTree(uint64_t universe_size) 
+    : universe_(universe_size), 
+      size_(0),
+      min_(NIL), 
+      max_(NIL),
+      is_base_case_(universe_size <= 2),
+      sqrt_size_(0) {
+    
+    if (universe_size == 0) {
+        throw std::invalid_argument("Universe size must be greater than 0");
+    }
+    
+    // Check if power of 2
+    if ((universe_size & (universe_size - 1)) != 0) {
+        throw std::invalid_argument("Universe size must be a power of 2");
+    }
+    
+    if (!is_base_case_) {
+        // Calculate sqrt of universe size
+        sqrt_size_ = 1ULL << (uint64_t)(std::log2((double)universe_size) / 2.0);
+        uint64_t num_clusters = universe_size / sqrt_size_;
+        
+        // Initialize clusters vector (but don't create trees yet - lazy allocation)
+        clusters_.resize(num_clusters);
+        
+        // Summary tree
+        summary_ = std::make_unique<VEBTree>(num_clusters);
+    }
+}
+
+void VEBTree::empty_insert(uint64_t key) {
+    min_ = max_ = static_cast<int64_t>(key);
+    size_ = 1;
+}
+
+void VEBTree::empty_delete() {
+    min_ = max_ = NIL;
+    size_ = 0;
+}
+
+bool VEBTree::insert(uint64_t key) {
+    if (key >= universe_) {
+        throw std::out_of_range("Key exceeds universe size");
+    }
+    
+    // Check if already present
+    if (contains(key)) {
+        return false;
+    }
+    
+    // Empty tree
+    if (min_ == NIL) {
+        empty_insert(key);
+        return true;
+    }
+    
+    // Base case
+    if (is_base_case_) {
+        if (static_cast<int64_t>(key) < min_) {
+            min_ = static_cast<int64_t>(key);
+        }
+        if (static_cast<int64_t>(key) > max_) {
+            max_ = static_cast<int64_t>(key);
+        }
+        size_++;
+        return true;
+    }
+    
+    // Make sure key is not min/max
+    if (static_cast<int64_t>(key) < min_) {
+        uint64_t temp = static_cast<uint64_t>(min_);
+        min_ = static_cast<int64_t>(key);
+        key = temp;
+    }
+    
+    if (static_cast<int64_t>(key) > max_) {
+        max_ = static_cast<int64_t>(key);
+    }
+    
+    // Recursive case
+    uint64_t h = high(key);
+    uint64_t l = low(key);
+    
+    // Lazy allocation of cluster
+    if (!clusters_[h]) {
+        clusters_[h] = std::make_unique<VEBTree>(sqrt_size_);
+    }
+    
+    // If cluster was empty, update summary
+    if (clusters_[h]->min_ == NIL) {
+        summary_->insert(h);
+        clusters_[h]->empty_insert(l);
+    } else {
+        clusters_[h]->insert(l);
+    }
+    
+    size_++;
+    return true;
+}
+
+bool VEBTree::remove(uint64_t key) {
+    if (key >= universe_) {
+        return false;
+    }
+    
+    if (min_ == NIL) {
+        return false; // Tree is empty
+    }
+    
+    if (!contains(key)) {
+        return false;
+    }
+    
+    // Base case: universe size 2
+    if (is_base_case_) {
+        if (static_cast<int64_t>(key) == min_ && static_cast<int64_t>(key) == max_) {
+            empty_delete();
+        } else if (static_cast<int64_t>(key) == min_) {
+            min_ = max_;
+        } else {
+            max_ = min_;
+        }
+        size_--;
+        return true;
+    }
+    
+    // Only one element
+    if (size_ == 1) {
+        empty_delete();
+        return true;
+    }
+    
+    // If deleting min, replace with successor
+    if (static_cast<int64_t>(key) == min_) {
+        int64_t first_cluster = summary_->min();
+        key = index(static_cast<uint64_t>(first_cluster), static_cast<uint64_t>(clusters_[first_cluster]->min()));
+        min_ = static_cast<int64_t>(key);
+    }
+    
+    // Recursive delete
+    uint64_t h = high(key);
+    uint64_t l = low(key);
+    
+    if (clusters_[h]) {
+        clusters_[h]->remove(l);
+        
+        // If cluster is now empty, remove from summary
+        if (clusters_[h]->min_ == NIL) {
+            summary_->remove(h);
+            clusters_[h].reset(); // Free memory
+            
+            // Update max if we deleted it
+            if (static_cast<int64_t>(key) == max_) {
+                int64_t summary_max = summary_->max();
+                if (summary_max == NIL) {
+                    max_ = min_;
+                } else {
+                    max_ = index(static_cast<uint64_t>(summary_max), static_cast<uint64_t>(clusters_[summary_max]->max()));
+                }
+            }
+        } else if (static_cast<int64_t>(key) == max_) {
+            // Update max but cluster not empty
+            max_ = index(h, static_cast<uint64_t>(clusters_[h]->max()));
+        }
+    }
+    
+    size_--;
+    return true;
+}
+
+bool VEBTree::contains(uint64_t key) const {
+    if (key >= universe_) {
+        return false;
+    }
+    
+    if (static_cast<int64_t>(key) == min_ || static_cast<int64_t>(key) == max_) {
+        return true;
+    }
+    
+    if (is_base_case_) {
+        return false;
+    }
+    
+    uint64_t h = high(key);
+    uint64_t l = low(key);
+    
+    if (clusters_[h]) {
+        return clusters_[h]->contains(l);
+    }
+    
+    return false;
+}
+
+int64_t VEBTree::min() const {
+    return min_;
+}
+
+int64_t VEBTree::max() const {
+    return max_;
+}
+
+int64_t VEBTree::successor(uint64_t key) const {
+    if (min_ == NIL) {
+        return NIL;
+    }
+    
+    // Base case
+    if (is_base_case_) {
+        if (static_cast<int64_t>(key) < min_) {
+            return min_;
+        } else if (static_cast<int64_t>(key) < max_) {
+            return max_;
+        } else {
+            return NIL;
+        }
+    }
+    
+    // If key < min, min is the successor
+    if (static_cast<int64_t>(key) < min_) {
+        return min_;
+    }
+    
+    uint64_t h = high(key);
+    uint64_t l = low(key);
+    
+    // Check if successor is in same cluster
+    if (clusters_[h] && static_cast<int64_t>(l) < clusters_[h]->max()) {
+        int64_t offset = clusters_[h]->successor(l);
+        return static_cast<int64_t>(index(h, static_cast<uint64_t>(offset)));
+    }
+    
+    // Successor is in next cluster
+    int64_t succ_cluster = summary_->successor(h);
+    if (succ_cluster == NIL) {
+        return NIL;
+    }
+    
+    int64_t offset = clusters_[succ_cluster]->min();
+    return static_cast<int64_t>(index(static_cast<uint64_t>(succ_cluster), static_cast<uint64_t>(offset)));
+}
+
+int64_t VEBTree::predecessor(uint64_t key) const {
+    if (max_ == NIL) {
+        return NIL;
+    }
+    
+    // Base case
+    if (is_base_case_) {
+        if (static_cast<int64_t>(key) > max_) {
+            return max_;
+        } else if (static_cast<int64_t>(key) > min_) {
+            return min_;
+        } else {
+            return NIL;
+        }
+    }
+    
+    // If key > max, max is the predecessor
+    if (static_cast<int64_t>(key) > max_) {
+        return max_;
+    }
+    
+    uint64_t h = high(key);
+    uint64_t l = low(key);
+    
+    // Check if predecessor is in same cluster
+    if (clusters_[h] && static_cast<int64_t>(l) > clusters_[h]->min()) {
+        int64_t offset = clusters_[h]->predecessor(l);
+        return static_cast<int64_t>(index(h, static_cast<uint64_t>(offset)));
+    }
+    
+    // Predecessor might be in previous cluster
+    int64_t pred_cluster = summary_->predecessor(h);
+    if (pred_cluster == NIL) {
+        // Predecessor might be min
+        if (static_cast<int64_t>(key) > min_) {
+            return min_;
+        }
+        return NIL;
+    }
+    
+    int64_t offset = clusters_[pred_cluster]->max();
+    return static_cast<int64_t>(index(static_cast<uint64_t>(pred_cluster), static_cast<uint64_t>(offset)));
+}
+
+void VEBTree::clear() {
+    min_ = max_ = NIL;
+    size_ = 0;
+    
+    if (!is_base_case_) {
+        summary_->clear();
+        for (auto& cluster : clusters_) {
+            cluster.reset();
+        }
+    }
+}
+
+std::vector<uint64_t> VEBTree::to_vector() const {
+    std::vector<uint64_t> result;
+    result.reserve(size_);
+    
+    if (min_ == NIL) {
+        return result;
+    }
+    
+    int64_t current = min_;
+    while (current != NIL) {
+        result.push_back(static_cast<uint64_t>(current));
+        if (current == max_) break;
+        current = successor(static_cast<uint64_t>(current));
+    }
+    
+    return result;
+}
+
+// ============================================================================
+// Ruby Wrapper Implementation
+// ============================================================================
+
+static const rb_data_type_t veb_tree_type = {
+    "VebTree::Tree",
+    {
+        nullptr, // dmark
+        [](void* ptr) { delete static_cast<VEBTree*>(ptr); }, // dfree
+        nullptr, // dsize
+        nullptr, // dcompact
+    },
+    nullptr, // parent
+    nullptr, // data
+    RUBY_TYPED_FREE_IMMEDIATELY
+};
+
+VEBTree* TreeWrapper::get_tree(VALUE self) {
+    VEBTree* tree;
+    TypedData_Get_Struct(self, VEBTree, &veb_tree_type, tree);
+    return tree;
+}
+
+VALUE TreeWrapper::rb_alloc(VALUE klass) {
+    return TypedData_Wrap_Struct(klass, &veb_tree_type, nullptr);
+}
+
+VALUE TreeWrapper::rb_initialize(VALUE self, VALUE universe_size) {
+    Check_Type(universe_size, T_FIXNUM);
+    
+    uint64_t u = NUM2ULL(universe_size);
+    
+    if (u == 0) {
+        rb_raise(rb_eArgError, "Universe size must be greater than 0");
+    }
+    
+    // Round up to next power of 2
+    uint64_t rounded = 1ULL << (uint64_t)std::ceil(std::log2((double)u));
+    
+    if (rounded != u) {
+        rb_warn("Universe size %llu rounded up to next power of 2: %llu", 
+                (unsigned long long)u, (unsigned long long)rounded);
+    }
+    
+    VEBTree* tree = nullptr;
+    try {
+        tree = new VEBTree(rounded);
+    } catch (const std::exception& e) {
+        rb_raise(rb_eRuntimeError, "Failed to create VEB tree: %s", e.what());
+    }
+    
+    RTYPEDDATA_DATA(self) = tree;
+    return self;
+}
+
+VALUE TreeWrapper::rb_insert(VALUE self, VALUE key) {
+    Check_Type(key, T_FIXNUM);
+    
+    VEBTree* tree = get_tree(self);
+    uint64_t k = NUM2ULL(key);
+    
+    try {
+        bool inserted = tree->insert(k);
+        return inserted ? Qtrue : Qfalse;
+    } catch (const std::out_of_range& e) {
+        rb_raise(rb_eArgError, "Key out of range: %s", e.what());
+    } catch (const std::exception& e) {
+        rb_raise(rb_eRuntimeError, "Insert failed: %s", e.what());
+    }
+    
+    return Qfalse;
+}
+
+VALUE TreeWrapper::rb_delete(VALUE self, VALUE key) {
+    Check_Type(key, T_FIXNUM);
+    
+    VEBTree* tree = get_tree(self);
+    uint64_t k = NUM2ULL(key);
+    
+    try {
+        bool deleted = tree->remove(k);
+        return deleted ? Qtrue : Qfalse;
+    } catch (const std::exception& e) {
+        rb_raise(rb_eRuntimeError, "Delete failed: %s", e.what());
+    }
+    
+    return Qfalse;
+}
+
+VALUE TreeWrapper::rb_include(VALUE self, VALUE key) {
+    Check_Type(key, T_FIXNUM);
+    
+    VEBTree* tree = get_tree(self);
+    uint64_t k = NUM2ULL(key);
+    
+    return tree->contains(k) ? Qtrue : Qfalse;
+}
+
+VALUE TreeWrapper::rb_size(VALUE self) {
+    VEBTree* tree = get_tree(self);
+    return ULL2NUM(tree->size());
+}
+
+VALUE TreeWrapper::rb_universe_size(VALUE self) {
+    VEBTree* tree = get_tree(self);
+    return ULL2NUM(tree->universe_size());
+}
+
+VALUE TreeWrapper::rb_min(VALUE self) {
+    VEBTree* tree = get_tree(self);
+    int64_t m = tree->min();
+    return m == VEBTree::NIL ? Qnil : LL2NUM(m);
+}
+
+VALUE TreeWrapper::rb_max(VALUE self) {
+    VEBTree* tree = get_tree(self);
+    int64_t m = tree->max();
+    return m == VEBTree::NIL ? Qnil : LL2NUM(m);
+}
+
+VALUE TreeWrapper::rb_successor(VALUE self, VALUE key) {
+    Check_Type(key, T_FIXNUM);
+    
+    VEBTree* tree = get_tree(self);
+    uint64_t k = NUM2ULL(key);
+    
+    int64_t succ = tree->successor(k);
+    return succ == VEBTree::NIL ? Qnil : LL2NUM(succ);
+}
+
+VALUE TreeWrapper::rb_predecessor(VALUE self, VALUE key) {
+    Check_Type(key, T_FIXNUM);
+    
+    VEBTree* tree = get_tree(self);
+    uint64_t k = NUM2ULL(key);
+    
+    int64_t pred = tree->predecessor(k);
+    return pred == VEBTree::NIL ? Qnil : LL2NUM(pred);
+}
+
+VALUE TreeWrapper::rb_empty(VALUE self) {
+    VEBTree* tree = get_tree(self);
+    return tree->empty() ? Qtrue : Qfalse;
+}
+
+VALUE TreeWrapper::rb_clear(VALUE self) {
+    VEBTree* tree = get_tree(self);
+    tree->clear();
+    return self;
+}
+
+VALUE TreeWrapper::rb_to_a(VALUE self) {
+    VEBTree* tree = get_tree(self);
+    std::vector<uint64_t> elements = tree->to_vector();
+    
+    VALUE arr = rb_ary_new_capa(elements.size());
+    for (uint64_t elem : elements) {
+        rb_ary_push(arr, ULL2NUM(elem));
+    }
+    
+    return arr;
+}
+
+VALUE TreeWrapper::rb_each(VALUE self) {
+    VEBTree* tree = get_tree(self);
+    
+    if (!rb_block_given_p()) {
+        return rb_enumeratorize(self, ID2SYM(rb_intern("each")), 0, nullptr);
+    }
+    
+    std::vector<uint64_t> elements = tree->to_vector();
+    for (uint64_t elem : elements) {
+        rb_yield(ULL2NUM(elem));
+    }
+    
+    return self;
+}
+
+void TreeWrapper::define_class(VALUE module) {
+    VALUE cTree = rb_define_class_under(module, "Tree", rb_cObject);
+    
+    rb_define_alloc_func(cTree, rb_alloc);
+    rb_define_method(cTree, "initialize", RUBY_METHOD_FUNC(rb_initialize), 1);
+    rb_define_method(cTree, "insert", RUBY_METHOD_FUNC(rb_insert), 1);
+    rb_define_method(cTree, "delete", RUBY_METHOD_FUNC(rb_delete), 1);
+    rb_define_method(cTree, "include?", RUBY_METHOD_FUNC(rb_include), 1);
+    rb_define_alias(cTree, "member?", "include?");
+    rb_define_method(cTree, "size", RUBY_METHOD_FUNC(rb_size), 0);
+    rb_define_method(cTree, "universe_size", RUBY_METHOD_FUNC(rb_universe_size), 0);
+    rb_define_method(cTree, "min", RUBY_METHOD_FUNC(rb_min), 0);
+    rb_define_method(cTree, "max", RUBY_METHOD_FUNC(rb_max), 0);
+    rb_define_method(cTree, "successor", RUBY_METHOD_FUNC(rb_successor), 1);
+    rb_define_method(cTree, "predecessor", RUBY_METHOD_FUNC(rb_predecessor), 1);
+    rb_define_method(cTree, "empty?", RUBY_METHOD_FUNC(rb_empty), 0);
+    rb_define_method(cTree, "clear", RUBY_METHOD_FUNC(rb_clear), 0);
+    rb_define_method(cTree, "to_a", RUBY_METHOD_FUNC(rb_to_a), 0);
+    rb_define_method(cTree, "each", RUBY_METHOD_FUNC(rb_each), 0);
+    
+    // Include Enumerable
+    rb_include_module(cTree, rb_mEnumerable);
+}
+
+} // namespace VebTree
+
+extern "C" void Init_veb_tree() {
+    VALUE mVebTree = rb_define_module("VebTree");
+    VebTree::TreeWrapper::define_class(mVebTree);
+}

data/ext/veb_tree/veb_tree_ext.h

@@ -0,0 +1,109 @@
+#ifndef VEB_TREE_EXT_H
+#define VEB_TREE_EXT_H
+
+#include <ruby.h>
+#include <cstdint>
+#include <memory>
+#include <stdexcept>
+#include <cmath>
+#include <vector>
+#include <limits>
+
+extern "C" {
+    void Init_veb_tree();
+}
+
+namespace VebTree {
+
+/**
+ * Van Emde Boas Tree - Full Implementation
+ * 
+ * Provides O(log log U) operations for integer sets
+ * where U is the universe size (must be power of 2)
+ */
+class VEBTree {
+public:
+    // NIL sentinel value - must be public for TreeWrapper access
+    static constexpr int64_t NIL = -1;
+    
+    explicit VEBTree(uint64_t universe_size);
+    ~VEBTree() = default;
+
+    // Core operations
+    bool insert(uint64_t key);
+    bool remove(uint64_t key);
+    bool contains(uint64_t key) const;
+    
+    // Min/Max - O(1)
+    int64_t min() const;
+    int64_t max() const;
+    
+    // Successor/Predecessor - O(log log U)
+    int64_t successor(uint64_t key) const;
+    int64_t predecessor(uint64_t key) const;
+    
+    // Utility
+    uint64_t size() const { return size_; }
+    uint64_t universe_size() const { return universe_; }
+    bool empty() const { return size_ == 0; }
+    void clear();
+    
+    // For enumeration
+    std::vector<uint64_t> to_vector() const;
+
+private:
+    uint64_t universe_;
+    uint64_t size_;
+    
+    // vEB tree structure
+    int64_t min_;
+    int64_t max_;
+    
+    // For base case (universe <= 2)
+    bool is_base_case_;
+    
+    // For recursive case
+    std::unique_ptr<VEBTree> summary_;
+    std::vector<std::unique_ptr<VEBTree>> clusters_;
+    uint64_t sqrt_size_;
+    
+    // Helper functions
+    uint64_t high(uint64_t x) const { return x / sqrt_size_; }
+    uint64_t low(uint64_t x) const { return x % sqrt_size_; }
+    uint64_t index(uint64_t high, uint64_t low) const { return high * sqrt_size_ + low; }
+    
+    void empty_insert(uint64_t key);
+    void empty_delete();
+};
+
+/**
+ * Ruby wrapper class
+ */
+class TreeWrapper {
+public:
+    static void define_class(VALUE module);
+    
+private:
+    static VALUE rb_alloc(VALUE klass);
+    static void rb_free(void* ptr);
+    static VALUE rb_initialize(VALUE self, VALUE universe_size);
+    static VALUE rb_insert(VALUE self, VALUE key);
+    static VALUE rb_delete(VALUE self, VALUE key);
+    static VALUE rb_include(VALUE self, VALUE key);
+    static VALUE rb_size(VALUE self);
+    static VALUE rb_universe_size(VALUE self);
+    static VALUE rb_min(VALUE self);
+    static VALUE rb_max(VALUE self);
+    static VALUE rb_successor(VALUE self, VALUE key);
+    static VALUE rb_predecessor(VALUE self, VALUE key);
+    static VALUE rb_empty(VALUE self);
+    static VALUE rb_clear(VALUE self);
+    static VALUE rb_to_a(VALUE self);
+    static VALUE rb_each(VALUE self);
+    
+    static VEBTree* get_tree(VALUE self);
+};
+
+} // namespace VebTree
+
+#endif // VEB_TREE_EXT_H

data/lib/veb_tree/pure_ruby.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require 'set'
+
+module VebTree
+  class PureRuby
+    attr_reader :universe_size, :size
+    
+    NIL_VALUE = -1
+    
+    def initialize(universe_size)
+      raise ArgumentError, "Universe size must be positive" if universe_size <= 0
+      
+      @universe_size = next_power_of_2(universe_size)
+      warn "Universe size #{universe_size} rounded up to #{@universe_size}" if @universe_size != universe_size
+      
+      @size = 0
+      @min = NIL_VALUE
+      @max = NIL_VALUE
+      
+      # Base case
+      if @universe_size <= 2
+        @base_case = true
+        return
+      end
+      
+      @base_case = false
+      
+      # Calculate sqrt
+      log_u = Math.log2(@universe_size).to_i
+      @sqrt_size = 1 << (log_u / 2)
+      @num_clusters = @universe_size / @sqrt_size
+      
+      # Lazy allocation
+      @clusters = Array.new(@num_clusters)
+      @summary = nil
+    end
+    
+    def insert(key)
+      validate_key(key)
+      return false if include?(key)
+      
+      # Empty tree
+      if @min == NIL_VALUE
+        @min = @max = key
+        @size += 1
+        return true
+      end
+      
+      # Base case
+      if @base_case
+        @min = key if key < @min
+        @max = key if key > @max
+        @size += 1
+        return true
+      end
+      
+      # Ensure key is not min
+      if key < @min
+        key, @min = @min, key
+      end
+      
+      @max = key if key > @max
+      
+      # Recursive insert
+      h = high(key)
+      l = low(key)
+      
+      # Lazy create cluster
+      @clusters[h] ||= PureRuby.new(@sqrt_size)
+      
+      # If cluster was empty, update summary
+      if @clusters[h].min == NIL_VALUE
+        @summary ||= PureRuby.new(@num_clusters)
+        @summary.insert(h)
+        @clusters[h].instance_variable_set(:@min, l)
+        @clusters[h].instance_variable_set(:@max, l)
+        @clusters[h].instance_variable_set(:@size, 1)
+      else
+        @clusters[h].insert(l)
+      end
+      
+      @size += 1
+      true
+    end
+    
+    def delete(key)
+      return false unless include?(key)
+      
+      # Base case
+      if @base_case
+        if key == @min && key == @max
+          @min = @max = NIL_VALUE
+        elsif key == @min
+          @min = @max
+        else
+          @max = @min
+        end
+        @size -= 1
+        return true
+      end
+      
+      # Only one element
+      if @size == 1
+        @min = @max = NIL_VALUE
+        @size = 0
+        return true
+      end
+      
+      # Replace min with successor if deleting min
+      if key == @min
+        first_cluster = @summary.min
+        key = index(first_cluster, @clusters[first_cluster].min)
+        @min = key
+      end
+      
+      # Recursive delete
+      h = high(key)
+      l = low(key)
+      
+      @clusters[h].delete(l) if @clusters[h]
+      
+      # If cluster is empty, remove from summary
+      if @clusters[h] && @clusters[h].min == NIL_VALUE
+        @summary.delete(h)
+        @clusters[h] = nil
+        
+        # Update max if necessary
+        if key == @max
+          summary_max = @summary.max
+          if summary_max == NIL_VALUE
+            @max = @min
+          else
+            @max = index(summary_max, @clusters[summary_max].max)
+          end
+        end
+      elsif key == @max && @clusters[h]
+        @max = index(h, @clusters[h].max)
+      end
+      
+      @size -= 1
+      true
+    end
+    
+    def include?(key)
+      return false if key < 0 || key >= @universe_size
+      return true if key == @min || key == @max
+      return false if @base_case
+      
+      h = high(key)
+      @clusters[h] && @clusters[h].include?(low(key))
+    end
+    alias member? include?
+    
+    def min
+      @min == NIL_VALUE ? nil : @min
+    end
+    
+    def max
+      @max == NIL_VALUE ? nil : @max
+    end
+    
+    def successor(key)
+      return nil if @min == NIL_VALUE
+      
+      # Base case
+      if @base_case
+        return @min if key < @min
+        return @max if key < @max
+        return nil
+      end
+      
+      return @min if key < @min
+      
+      h = high(key)
+      l = low(key)
+      
+      # Check same cluster
+      if @clusters[h] && l < @clusters[h].max
+        offset = @clusters[h].successor(l)
+        return index(h, offset)
+      end
+      
+      # Next cluster
+      succ_cluster = @summary.successor(h)
+      return nil if succ_cluster == NIL_VALUE
+      
+      offset = @clusters[succ_cluster].min
+      index(succ_cluster, offset)
+    end
+    
+    def predecessor(key)
+      return nil if @max == NIL_VALUE
+      
+      # Base case
+      if @base_case
+        return @max if key > @max
+        return @min if key > @min
+        return nil
+      end
+      
+      return @max if key > @max
+      
+      h = high(key)
+      l = low(key)
+      
+      # Check same cluster
+      if @clusters[h] && l > @clusters[h].min
+        offset = @clusters[h].predecessor(l)
+        return index(h, offset)
+      end
+      
+      # Previous cluster
+      pred_cluster = @summary.predecessor(h)
+      return @min if pred_cluster == NIL_VALUE && key > @min
+      return nil if pred_cluster == NIL_VALUE
+      
+      offset = @clusters[pred_cluster].max
+      index(pred_cluster, offset)
+    end
+    
+    def empty?
+      @size == 0
+    end
+    
+    def clear
+      @min = @max = NIL_VALUE
+      @size = 0
+      unless @base_case
+        @summary&.clear
+        @clusters.fill(nil)
+      end
+      self
+    end
+    
+    def each
+      return enum_for(:each) unless block_given?
+      
+      current = @min
+      while current && current != NIL_VALUE
+        yield current
+        break if current == @max
+        current = successor(current)
+      end
+      
+      self
+    end
+    
+    def to_a
+      each.to_a
+    end
+    
+    private
+    
+    def high(x)
+      x / @sqrt_size
+    end
+    
+    def low(x)
+      x % @sqrt_size
+    end
+    
+    def index(high, low)
+      high * @sqrt_size + low
+    end
+    
+    def validate_key(key)
+      raise ArgumentError, "Key must be non-negative" if key < 0
+      raise ArgumentError, "Key #{key} exceeds universe size #{@universe_size}" if key >= @universe_size
+    end
+    
+    def next_power_of_2(n)
+      return 1 if n <= 1
+      2 ** (Math.log2(n).ceil)
+    end
+  end
+end

data/lib/veb_tree/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module VebTree
+  VERSION = "0.1.0"
+end

data/lib/veb_tree.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative "veb_tree/version"
+
+module VebTree
+  class Error < StandardError; end
+  
+  # Load the native extension
+  begin
+    require_relative "veb_tree/veb_tree"
+    NATIVE_EXTENSION_LOADED = true
+  rescue LoadError => e
+    raise Error, <<~MSG
+      Failed to load VebTree native extension!
+      
+      Error: #{e.message}
+      
+      VebTree requires a C++17 compatible compiler to build the native extension.
+      
+      Requirements:
+        - Linux: GCC 7+ or Clang 5+
+        - macOS: Xcode Command Line Tools
+        - Windows: MinGW-w64 or MSVC 2017+
+      
+      To install:
+        1. Install a C++ compiler for your platform
+        2. Run: gem install veb_tree
+      
+      For more help, see: https://github.com/yourusername/veb_tree
+    MSG
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: veb_tree
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- pixelcaliber
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2025-10-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: "VebTree is a production-quality Van Emde Boas tree implementation providing
+  \nO(log log U) time complexity for insert, delete, search, successor, and \npredecessor
+  operations on integer sets. The core algorithm is implemented \nin C++17 for maximum
+  performance with an idiomatic Ruby API.\n\nPerfect for applications requiring fast
+  integer set operations, range queries,\nand successor/predecessor lookups within
+  a bounded universe.\n"
+email:
+- abhinav.1e4@gmail.com
+executables: []
+extensions:
+- ext/veb_tree/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- ext/veb_tree/extconf.rb
+- ext/veb_tree/veb_tree_ext.cpp
+- ext/veb_tree/veb_tree_ext.h
+- lib/veb_tree.rb
+- lib/veb_tree/pure_ruby.rb
+- lib/veb_tree/version.rb
+homepage: https://github.com/abhinvv1/Van-Emde-Boas-tree
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/abhinvv1/Van-Emde-Boas-tree
+  source_code_uri: https://github.com/abhinvv1/Van-Emde-Boas-tree
+  changelog_uri: https://github.com/abhinvv1/Van-Emde-Boas-tree/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/abhinvv1/Van-Emde-Boas-tree/issues
+  documentation_uri: https://rubydoc.info/gems/veb_tree
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.9
+signing_key: 
+specification_version: 4
+summary: High-performance Van Emde Boas tree for integer sets with O(log log U) operations
+test_files: []