ruby-fst 0.2.0-x64-mingw-ucrt

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9b31a9e023439fc14954b754fa2436e85ffa31c1b17a38c59c67cf790b35fad6
+  data.tar.gz: 66ca8d5e9c2dcd370ce14ccfb48712fff21fc087bf25c8a32cc1993f19fa7025
+SHA512:
+  metadata.gz: 031f8bf7bfde299f4e3133d423d43403880d6aedbe1201d39fd9a082ccaebdef9cb1fcd0401237f795f3c2068d53f1a6302119688f6f71f8f2be2b31895baf39
+  data.tar.gz: 183ca46a0001a7ed95b51de6db5c0d57f1d6b2a58bd2e3b40f5dcdeea5ac20aa51ce09027df96c3a1b1fe8a8db4f3dc446258b0f9f6c72026d2324b763f2bc50

data/.rubocop.yml

@@ -0,0 +1,82 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-rake
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.2
+  SuggestExtensions: false
+  Exclude:
+    - 'target/**/*'
+    - 'tmp/**/*'
+    - 'pkg/**/*'
+    - 'vendor/**/*'
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Style/SymbolArray:
+  EnforcedStyle: percent
+  MinSize: 3
+
+Style/WordArray:
+  EnforcedStyle: percent
+  MinSize: 3
+
+Style/PercentLiteralDelimiters:
+  PreferredDelimiters:
+    default: '()'
+    '%i': '()'
+    '%w': '()'
+
+Style/Documentation:
+  Enabled: false
+
+Style/HashEachMethods:
+  Exclude:
+    - 'test/**/*'
+
+Style/MapIntoArray:
+  Exclude:
+    - 'test/**/*'
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - ge
+    - le
+    - id
+    - to
+    - by
+    - on
+    - in
+    - at
+    - of
+    - or
+    - if
+    - is
+    - as
+    - it
+
+Naming/VariableNumber:
+  CheckMethodNames: false
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  Exclude:
+    - 'test/**/*'
+    - '*.gemspec'
+    - 'Rakefile'
+
+Metrics/MethodLength:
+  Max: 25
+
+Metrics/AbcSize:
+  Max: 25
+
+Minitest/MultipleAssertions:
+  Max: 8

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] — 2026-05-13
+
+### Added
+- `Map.from_path_mmap` and `Set.from_path_mmap` for memory-mapped loading of large FSTs.
+- `Map#range(ge:, le:)` and `Set#range(ge:, le:)` streaming range iteration.
+- `Map#starts_with(prefix)` and `Set#starts_with(prefix)` prefix scans.
+- `Map#get_le_value` and `Map#get_ge_value` — return only the value (no key allocation) for floor/ceiling lookups.
+- Precompiled native gems for Linux (x86_64, aarch64), macOS (x86_64, arm64), and Windows (x64) — installs without a Rust toolchain on those platforms.
+- Tests covering binary string encoding, key lifetime after stream drop, builder GC, and 0xFF prefix-scan edge case.
+- RuboCop lint configuration with rubocop-minitest and rubocop-rake plugins; runs as part of `rake` and as a CI gate.
+
+### Changed
+- Minimum Ruby version raised to 3.2.
+- `MapBuilder` and `SetBuilder` now operate on a generic `Storage` backing (heap or mmap) for both `Map` and `Set`.
+- Upgraded to magnus 0.8 (drops support for Ruby 2.7 and 3.0 in the underlying bindings; we already require 3.2+).
+
+### Documentation
+- README clarifies key encoding, insertion order, mmap vs in-memory loading, and Levenshtein UTF-8 requirement.
+
+## [0.1.0] — 2026-05-13
+
+### Added
+- Initial release: `RubyFst::Map`, `RubyFst::Set`, `MapBuilder`, `SetBuilder`.
+- Floor/ceiling lookups (`get_le`, `get_ge`).
+- Levenshtein automaton search.
+- Bytes/file serialization via `to_bytes` / `save` / `from_path`.

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'minitest', '~> 5.0'
+gem 'rake', '~> 13.0'
+gem 'rake-compiler', '~> 1.2'
+gem 'rubocop', '~> 1.60', require: false
+gem 'rubocop-minitest', '~> 0.34', require: false
+gem 'rubocop-rake', '~> 0.6', require: false

data/LICENSE.txt

@@ -0,0 +1,46 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Denis Sablic
+
+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.
+
+---
+
+This gem wraps the fst crate (https://github.com/BurntSushi/fst) by
+Andrew Gallant, which is licensed under the MIT License:
+
+  Copyright (c) 2015 Andrew Gallant
+
+  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,174 @@
+# ruby-fst
+
+[![CI](https://github.com/dsablic/ruby-fst/actions/workflows/ci.yml/badge.svg)](https://github.com/dsablic/ruby-fst/actions/workflows/ci.yml) [![Gem Version](https://badge.fury.io/rb/ruby-fst.svg)](https://badge.fury.io/rb/ruby-fst) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](/LICENSE.txt) [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red.svg)](https://www.ruby-lang.org/)
+
+Ruby bindings for the [fst](https://github.com/BurntSushi/fst) crate by Andrew Gallant. Provides finite state transducer backed ordered maps and sets with fast lookup, prefix and range scans, floor/ceiling lookups, and Levenshtein fuzzy search.
+
+## Requirements
+
+- Ruby >= 3.2
+- For source installs: a Rust toolchain. Precompiled gems are published for Linux (x86_64, aarch64, glibc and musl), macOS (x86_64, arm64), and Windows (x64) — these install with no Rust toolchain required.
+
+## Installation
+
+```
+gem install ruby-fst
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'ruby-fst'
+```
+
+## Keys are byte strings
+
+All FST keys are arbitrary byte strings (`Encoding::BINARY`). When a key is returned from the gem (e.g. via `each`, `get_le`, `range`) it always carries the `Encoding::BINARY` encoding — be careful when interpolating into UTF-8 strings or `puts`-ing keys that contain non-ASCII bytes.
+
+Keys must be inserted into a builder in **strictly ascending lexicographic byte order**, with no duplicates. Out-of-order or duplicate inserts raise.
+
+## Map
+
+Ordered map from byte string keys to unsigned 64-bit integer values.
+
+```ruby
+require 'ruby_fst'
+
+builder = RubyFst::MapBuilder.new
+builder.insert('bar', 2)
+builder.insert('baz', 3)
+builder.insert('foo', 1)
+map = RubyFst::Map.new(builder.finish)
+
+map['foo']             # => 1
+map.get('missing')     # => nil
+map.contains?('bar')   # => true
+map.length             # => 3
+
+map.each { |key, value| puts("#{key}: #{value}") }
+```
+
+## Set
+
+Ordered set of byte string keys.
+
+```ruby
+builder = RubyFst::SetBuilder.new
+builder.insert('bar')
+builder.insert('baz')
+builder.insert('foo')
+set = RubyFst::Set.new(builder.finish)
+
+set.contains?('foo')   # => true
+set.length             # => 3
+
+set.each { |key| puts(key) }
+```
+
+## Range queries
+
+`Map#range` and `Set#range` stream every entry whose key falls in `[ge, le]`. Either bound may be omitted.
+
+```ruby
+map.range(ge: 'b', le: 'f') { |key, value| puts("#{key} -> #{value}") }
+map.range(ge: 'b').to_a                      # Enumerator without a block
+set.range(le: 'baz') { |key| puts(key) }
+```
+
+`Map#starts_with` and `Set#starts_with` stream every entry whose key begins with the given prefix.
+
+```ruby
+map.starts_with('foo') { |key, value| puts("#{key} -> #{value}") }
+set.starts_with('app').to_a
+```
+
+## Floor and ceiling lookups
+
+`get_le` returns the greatest key less than or equal to the query. `get_ge` returns the smallest key greater than or equal to the query. Both return `[key, value]` or `nil`.
+
+```ruby
+builder = RubyFst::MapBuilder.new
+builder.insert('bar', 1)
+builder.insert('foo', 2)
+builder.insert('qux', 3)
+map = RubyFst::Map.new(builder.finish)
+
+map.get_le('dog')   # => ["bar", 1]
+map.get_ge('dog')   # => ["foo", 2]
+map.get_le('aaa')   # => nil
+```
+
+For range lookups where you only need the value, `get_le_value` and `get_ge_value` skip key reconstruction and return only the `Integer` (or `nil`):
+
+```ruby
+map.get_le_value('dog')   # => 1
+map.get_ge_value('dog')   # => 2
+map.get_le_value('aaa')   # => nil
+```
+
+This is useful for IP range lookups. Encode range starts as 4-byte big-endian keys and use `get_le_value` to find which range an IP falls into:
+
+```ruby
+require 'ipaddr'
+
+builder = RubyFst::MapBuilder.new
+builder.insert([167_772_160].pack('N'), 1)   # 10.0.0.0
+builder.insert([3_232_235_520].pack('N'), 2) # 192.168.0.0
+map = RubyFst::Map.new(builder.finish)
+
+ip = IPAddr.new('10.0.0.100').to_i
+label_id = map.get_le_value([ip].pack('N'))
+```
+
+## Levenshtein search
+
+Find all keys within a given edit distance. The search runs as an automaton intersection with the FST, visiting only reachable states.
+
+The query must be valid UTF-8 (the Levenshtein automaton is defined over Unicode codepoints), but the keys themselves can be any bytes — the automaton matches against the UTF-8 interpretation of the keys.
+
+```ruby
+builder = RubyFst::MapBuilder.new
+%w(bar baz cat foo fun).each_with_index { |w, i| builder.insert(w, i) }
+map = RubyFst::Map.new(builder.finish)
+
+map.search_levenshtein('far', 1) { |key, value| puts(key) }
+# => bar
+```
+
+Works on sets too:
+
+```ruby
+set.search_levenshtein('university', 2) { |key| puts(key) }
+```
+
+## Serialization
+
+```ruby
+# Bytes
+bytes = map.to_bytes              # binary string
+map = RubyFst::Map.new(bytes)
+
+# File: read entire file into memory (good for small/medium FSTs)
+map.save('/path/to/file.fst')
+map = RubyFst::Map.from_path('/path/to/file.fst')
+
+# File: memory-map the file (good for large FSTs; lookups page in only what they touch)
+map = RubyFst::Map.from_path_mmap('/path/to/file.fst')
+```
+
+When using `from_path_mmap`, the file must remain unchanged on disk for the lifetime of the resulting `Map` or `Set` — modifying or truncating it causes undefined behavior.
+
+## Development
+
+```
+bundle install
+bundle exec rake          # compile + test + rubocop
+```
+
+Individual tasks: `rake compile`, `rake test`, `rake rubocop`. Bump the version (and CHANGELOG) with `rake bump[patch]` / `rake bump[minor]` / `rake bump[major]`. Tagging `vX.Y.Z` on GitHub triggers cross-compile and publish to RubyGems.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt) for details.
+
+This gem wraps the [fst](https://github.com/BurntSushi/fst) crate by Andrew Gallant, also MIT licensed.

data/Rakefile

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+require 'rb_sys/extensiontask'
+require 'rubocop/rake_task'
+
+GEMSPEC = Gem::Specification.load('ruby_fst.gemspec')
+
+RbSys::ExtensionTask.new('ruby_fst', GEMSPEC) do |ext|
+  ext.lib_dir = 'lib/ruby_fst'
+  ext.cross_compile = true
+  ext.cross_platform = %w(
+    aarch64-linux
+    aarch64-linux-musl
+    arm64-darwin
+    x64-mingw-ucrt
+    x86_64-darwin
+    x86_64-linux
+    x86_64-linux-musl
+  )
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+RuboCop::RakeTask.new
+
+task default: %i(compile test rubocop)
+
+desc 'Bump version (rake bump[patch], rake bump[minor], rake bump[major])'
+task :bump, [:level] do |_, args|
+  level = args[:level] || 'patch'
+  version_file = File.join(__dir__, 'lib', 'ruby_fst', 'version.rb')
+  cargo_file = File.join(__dir__, 'ext', 'ruby_fst', 'Cargo.toml')
+  lock_file = File.join(__dir__, 'Cargo.lock')
+
+  content = File.read(version_file)
+  current = content[/VERSION = '(.+)'/, 1]
+  major, minor, patch = current.split('.').map(&:to_i)
+
+  new_version =
+    case level
+    when 'major' then "#{major + 1}.0.0"
+    when 'minor' then "#{major}.#{minor + 1}.0"
+    when 'patch' then "#{major}.#{minor}.#{patch + 1}"
+    else abort("Unknown level: #{level}. Use major, minor, or patch.")
+    end
+
+  File.write(version_file, content.sub(/VERSION = '.+'/, "VERSION = '#{new_version}'"))
+
+  cargo = File.read(cargo_file)
+  File.write(cargo_file, cargo.sub(/^version = ".+"/, "version = \"#{new_version}\""))
+
+  if File.exist?(lock_file)
+    lock = File.read(lock_file)
+    File.write(
+      lock_file,
+      lock.sub(
+        /(\[\[package\]\]\nname = "ruby_fst"\nversion = ").+(")/,
+        "\\1#{new_version}\\2"
+      )
+    )
+  end
+
+  changelog_file = File.join(__dir__, 'CHANGELOG.md')
+  if File.exist?(changelog_file)
+    changelog = File.read(changelog_file)
+    today = Time.now.utc.strftime('%Y-%m-%d')
+    promoted = changelog.sub(
+      '## [Unreleased]',
+      "## [Unreleased]\n\n## [#{new_version}] — #{today}"
+    )
+    File.write(changelog_file, promoted) if promoted != changelog
+  end
+
+  puts("#{current} -> #{new_version}")
+end

data/lib/ruby_fst/version.rb

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

data/lib/ruby_fst.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'ruby_fst/version'
+require_relative 'ruby_fst/ruby_fst'
+
+module RubyFst
+  module RangeQuery
+    def range(ge: nil, le: nil, &block)
+      return enum_for(:range, ge:, le:) unless block
+
+      _range(ge, le, &block)
+    end
+
+    def starts_with(prefix, &block)
+      return enum_for(:starts_with, prefix) unless block
+
+      _starts_with(prefix, &block)
+    end
+  end
+
+  class Map
+    include Enumerable
+
+    alias _range range
+    alias _starts_with starts_with
+    private :_range, :_starts_with
+
+    prepend RangeQuery
+  end
+
+  class Set
+    include Enumerable
+
+    alias _range range
+    alias _starts_with starts_with
+    private :_range, :_starts_with
+
+    prepend RangeQuery
+  end
+end

data/ruby_fst.gemspec

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require_relative 'lib/ruby_fst/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'ruby-fst'
+  spec.version = RubyFst::VERSION
+  spec.authors = ['Denis Sablic']
+  spec.email = ['denis.sablic@gmail.com']
+  spec.summary = 'Ruby bindings for the Rust fst crate'
+  spec.description = 'Finite state transducer backed ordered sets and maps via the Rust fst crate by BurntSushi'
+  spec.homepage = 'https://github.com/dsablic/ruby-fst'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+  spec.metadata['source_code_uri'] = 'https://github.com/dsablic/ruby-fst'
+  spec.metadata['changelog_uri'] = 'https://github.com/dsablic/ruby-fst/blob/main/CHANGELOG.md'
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject { |f| f.start_with?('test/', '.git') }
+  end
+  spec.extensions = ['ext/ruby_fst/extconf.rb']
+  spec.require_paths = ['lib']
+
+  spec.add_dependency('rb_sys', '~> 0.9')
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: ruby-fst
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: x64-mingw-ucrt
+authors:
+- Denis Sablic
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-05-13 00:00:00.000000000 Z
+dependencies: []
+description: Finite state transducer backed ordered sets and maps via the Rust fst
+  crate by BurntSushi
+email:
+- denis.sablic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ruby_fst.rb
+- lib/ruby_fst/3.2/ruby_fst.so
+- lib/ruby_fst/3.3/ruby_fst.so
+- lib/ruby_fst/3.4/ruby_fst.so
+- lib/ruby_fst/version.rb
+- ruby_fst.gemspec
+homepage: https://github.com/dsablic/ruby-fst
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/dsablic/ruby-fst
+  changelog_uri: https://github.com/dsablic/ruby-fst/blob/main/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 3.5.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Ruby bindings for the Rust fst crate
+test_files: []