hamt 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c5295a7442e167cb677bc71da0c89ed99ed90e91b40ffcd2eccf0221ab95b836
+  data.tar.gz: bc3d7a19547ce390a03ad73d10e221993f96b0f7d82f2ac0de4acbd076e836b2
+SHA512:
+  metadata.gz: 1ddd15320f29fb1e3ea594afd8f1b5c7476902c67eb29ad0eb30dde112ea6cd00a5d49dbb2a49adbba6640a734e686074516a187903552c3ec63f1b49d120876
+  data.tar.gz: 1d230de9f31182bbd61376015fbd4c440056ce8e7a5c1fa296af4585e54a95584e70446fe6a20c8822ade77a20feb995ad154be733378006325c16a3a53cfa11

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 John Hawthorn
+
+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,24 @@
+# HAMT
+
+A persistent (immutable) Hash Array Mapped Trie for Ruby.
+
+`set` and `delete` return a new HAMT that shares structure with the old one;
+nothing is ever mutated. Keys are compared the way Ruby's Hash compares them:
+by `#hash`, then `#eql?`.
+
+```ruby
+a = HAMT[x: 1]
+b = a.set(:y, 2)
+a[:y]  # => nil   (a is untouched)
+b[:y]  # => 2
+```
+
+## Installation
+
+```
+gem install hamt
+```
+
+## License
+
+MIT

data/lib/hamt/version.rb

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

data/lib/hamt.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require_relative "hamt/version"
+
+# A persistent (immutable) Hash Array Mapped Trie.
+#
+# `set` and `delete` return a new HAMT that shares structure with the old one;
+# nothing is ever mutated and every node is frozen. Keys are compared the way
+# Ruby's Hash compares them: by #hash, then #eql?.
+#
+#   a = HAMT[x: 1]
+#   b = a.set(:y, 2)
+#   a[:y]  # => nil   (a is untouched)
+#   b[:y]  # => 2
+#
+class HAMT
+  include Enumerable
+
+  BITS = 5            # 5 bits per level => 32-way branches
+  MASK = (1 << BITS) - 1
+
+  NOT_FOUND = Object.new
+  private_constant :NOT_FOUND
+
+  # In a key slot: the value slot holds a sub-node, not a value.
+  SUBNODE = Object.new
+  private_constant :SUBNODE
+
+  def self.popcount(int)
+    n = 0
+    while int != 0
+      int &= int - 1
+      n += 1
+    end
+    n
+  end
+
+  # array packs two cells per filled slot: [key, value] or [SUBNODE, child].
+  class Node
+    attr_reader :bitmap, :array
+
+    def initialize(bitmap, array)
+      @bitmap = bitmap
+      @array = array
+      freeze
+    end
+
+    def get(key, hash, shift, default)
+      bit = 1 << ((hash >> shift) & MASK)
+      return default if (bitmap & bit).zero?
+      i = 2 * index(bit)
+      k = array[i]
+      if k.equal?(SUBNODE)
+        array[i + 1].get(key, hash, shift + BITS, default)
+      elsif k.eql?(key)
+        array[i + 1]
+      else
+        default
+      end
+    end
+
+    def put(key, hash, shift, value, result)
+      bit = 1 << ((hash >> shift) & MASK)
+      i = 2 * index(bit)
+      if (bitmap & bit).zero?
+        result.count += 1
+        Node.new(bitmap | bit, insert2(array, i, key, value))
+      elsif (k = array[i]).equal?(SUBNODE)
+        child = array[i + 1]
+        new_child = child.put(key, hash, shift + BITS, value, result)
+        new_child.equal?(child) ? self : Node.new(bitmap, store1(array, i + 1, new_child))
+      elsif k.eql?(key)
+        return self if array[i + 1].equal?(value)
+        Node.new(bitmap, store1(array, i + 1, value))
+      else
+        # different key, same slot: push the existing pair down a level
+        ev = array[i + 1]
+        ehash = k.hash
+        child =
+          if ehash == hash
+            result.count += 1
+            Collision.new(hash, [k, ev, key, value].freeze)
+          else
+            sub = Node.new(1 << ((ehash >> (shift + BITS)) & MASK), [k, ev].freeze)
+            sub.put(key, hash, shift + BITS, value, result)
+          end
+        Node.new(bitmap, store2(array, i, SUBNODE, child))
+      end
+    end
+
+    def delete(key, hash, shift)
+      bit = 1 << ((hash >> shift) & MASK)
+      return self if (bitmap & bit).zero?
+      i = 2 * index(bit)
+      k = array[i]
+      if k.equal?(SUBNODE)
+        child = array[i + 1]
+        new_child = child.delete(key, hash, shift + BITS)
+        return self if new_child.equal?(child)
+        if new_child.nil?
+          rest = bitmap & ~bit
+          rest.zero? ? nil : Node.new(rest, remove2(array, i))
+        else
+          Node.new(bitmap, store1(array, i + 1, new_child))
+        end
+      elsif k.eql?(key)
+        rest = bitmap & ~bit
+        rest.zero? ? nil : Node.new(rest, remove2(array, i))
+      else
+        self
+      end
+    end
+
+    def each(&block)
+      i = 0
+      n = array.size
+      while i < n
+        k = array[i]
+        if k.equal?(SUBNODE)
+          array[i + 1].each(&block)
+        else
+          block.call([k, array[i + 1]])
+        end
+        i += 2
+      end
+    end
+
+    private def index(bit) = HAMT.popcount(bitmap & (bit - 1))
+
+    # [*a] beats Array#dup here: dup pays for rb_obj_dup_setup, splat is a
+    # raw copy (see bench/array_copy.rb).
+    private def insert2(a, i, x, y) = [*a].insert(i, x, y).freeze
+
+    private def store1(a, i, x)
+      b = [*a]
+      b[i] = x
+      b.freeze
+    end
+
+    private def store2(a, i, x, y)
+      b = [*a]
+      b[i] = x
+      b[i + 1] = y
+      b.freeze
+    end
+
+    private def remove2(a, i)
+      b = [*a]
+      b.slice!(i, 2)
+      b.freeze
+    end
+  end
+  private_constant :Node
+
+  # Flat [k, v, k, v, ...] bucket for keys with a fully-equal hash.
+  class Collision
+    attr_reader :hash, :array
+
+    def initialize(hash, array)
+      @hash = hash
+      @array = array
+      freeze
+    end
+
+    def get(key, _hash, _shift, default)
+      i = 0
+      n = array.size
+      while i < n
+        return array[i + 1] if array[i].eql?(key)
+        i += 2
+      end
+      default
+    end
+
+    def put(key, hash, shift, value, result)
+      return split(shift).put(key, hash, shift, value, result) unless hash == self.hash
+      i = 0
+      n = array.size
+      while i < n
+        if array[i].eql?(key)
+          return self if array[i + 1].equal?(value)
+          b = [*array]
+          b[i + 1] = value
+          return Collision.new(hash, b.freeze)
+        end
+        i += 2
+      end
+      result.count += 1
+      Collision.new(hash, ([*array] << key << value).freeze)
+    end
+
+    def delete(key, _hash, _shift)
+      i = 0
+      n = array.size
+      while i < n
+        if array[i].eql?(key)
+          return nil if n == 2
+          b = [*array]
+          b.slice!(i, 2)
+          return Collision.new(hash, b.freeze)
+        end
+        i += 2
+      end
+      self
+    end
+
+    def each
+      i = 0
+      n = array.size
+      while i < n
+        yield [array[i], array[i + 1]]
+        i += 2
+      end
+    end
+
+    private def split(shift) = Node.new(1 << ((hash >> shift) & MASK), [SUBNODE, self].freeze)
+  end
+  private_constant :Collision
+
+  def self.[](enum = [])
+    enum.reduce(new) { |h, (k, v)| h.set(k, v) }
+  end
+
+  def initialize(root = nil, count = 0)
+    @root = root
+    @count = count
+    freeze
+  end
+
+  attr_accessor :root, :count
+  alias size count
+  alias length count
+  def empty? = @count.zero?
+
+  def get(key, default = nil)
+    @root ? @root.get(key, key.hash, 0, default) : default
+  end
+
+  def [](key)
+    @root ? @root.get(key, key.hash, 0, nil) : nil
+  end
+
+  def key?(key)
+    return false unless @root
+    !@root.get(key, key.hash, 0, NOT_FOUND).equal?(NOT_FOUND)
+  end
+  alias has_key? key?
+  alias include? key?
+
+  def fetch(key, default = NOT_FOUND)
+    value = @root ? @root.get(key, key.hash, 0, NOT_FOUND) : NOT_FOUND
+    return value unless NOT_FOUND.equal?(value)
+    return yield(key) if block_given?
+    return default unless NOT_FOUND.equal?(default)
+    raise KeyError, "key not found: #{key.inspect}"
+  end
+
+  def set(key, value)
+    hash = key.hash
+    return HAMT.new(Node.new(1 << (hash & MASK), [key, value].freeze), 1) if @root.nil?
+
+    result = HAMT.allocate
+    result.count = @count
+    root = @root.put(key, hash, 0, value, result)
+    return self if root.equal?(@root)
+    result.root = root
+    result.freeze
+    result
+  end
+  alias store set
+  alias put set
+
+  def delete(key)
+    return self unless @root
+    root = @root.delete(key, key.hash, 0)
+    root.equal?(@root) ? self : HAMT.new(root, @count - 1)
+  end
+
+  def each(&block)
+    return enum_for(:each) { @count } unless block_given?
+    @root&.each(&block)
+    self
+  end
+
+  def merge(*others)
+    others.reduce(self) do |acc, other|
+      other.reduce(acc) do |h, (k, v)|
+        if block_given? && !(old = h.get(k, NOT_FOUND)).equal?(NOT_FOUND)
+          h.set(k, yield(k, old, v))
+        else
+          h.set(k, v)
+        end
+      end
+    end
+  end
+  def keys = map { |k, _| k }
+  def values = map { |_, v| v }
+  def to_h = each_with_object({}) { |(k, v), h| h[k] = v }
+
+  def ==(other)
+    other.is_a?(HAMT) && other.count == @count &&
+      all? { |k, v| other.get(k, NOT_FOUND) == v }
+  end
+
+  def inspect = "HAMT[#{map { |k, v| "#{k.inspect}=>#{v.inspect}" }.join(', ')}]"
+  alias to_s inspect
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification
+name: hamt
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- John Hawthorn
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A persistent (immutable) Hash Array Mapped Trie
+email:
+- john@hawthorn.email
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/hamt.rb
+- lib/hamt/version.rb
+homepage: https://github.com/jhawthorn/hamt
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jhawthorn/hamt
+  source_code_uri: https://github.com/jhawthorn/hamt
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: A persistent (immutable) Hash Array Mapped Trie
+test_files: []