ruby-fst 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 82d0d6d69fc9c3c580ecd104cd588bf669d2d8d269e6e73ccdb3650e571ece14
+  data.tar.gz: 300c838ff26a9e6fc790ead10d403cfd19c419a40b329f684221bd29b60e7607
+SHA512:
+  metadata.gz: b5d38c9b3cb260f1632929bd2adce4d5b6f13e6fb7273d2a8af4e69667fe0a36ddf60a1524e48775f6bad0b5954b2e981d0e3bb6428b014ea2ce187e21d10ffb
+  data.tar.gz: 6fb9e1d99c4888032eb5f3c0a4657dd0ea5498ad85d6aec28c5bc2da727975006331d7007706a9d3ccfb141b9884545a723ba4e070228ce482eeb5ac3a5abbf6

data/Cargo.lock

@@ -0,0 +1,298 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "bindgen"
+version = "0.72.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "993776b509cfb49c750f11b8f07a46fa23e0a1386ffc01fb1e7d343efc387895"
+dependencies = [
+ "bitflags",
+ "cexpr",
+ "clang-sys",
+ "itertools",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "rustc-hash",
+ "shlex",
+ "syn",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
+
+[[package]]
+name = "cexpr"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6fac387a98bb7c37292057cffc56d62ecb629900026402633ae9160df93a8766"
+dependencies = [
+ "nom",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "clang-sys"
+version = "1.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b023947811758c97c59bf9d1c188fd619ad4718dcaa767947df1cadb14f39f4"
+dependencies = [
+ "glob",
+ "libc",
+ "libloading",
+]
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "fst"
+version = "0.4.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ab85b9b05e3978cc9a9cf8fea7f01b494e1a09ed3037e16ba39edc7a29eb61a"
+dependencies = [
+ "utf8-ranges",
+]
+
+[[package]]
+name = "glob"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0cc23270f6e1808e30a928bdc84dea0b9b4136a8bc82338574f23baf47bbd280"
+
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "lazy_static"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bbd2bcb4c963f2ddae06a2efc7e9f3591312473c50c6685e1f298068316e66fe"
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "libloading"
+version = "0.8.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7c4b02199fee7c5d21a5ae7d8cfa79a6ef5bb2fc834d6e9058e89c825efdc55"
+dependencies = [
+ "cfg-if",
+ "windows-link",
+]
+
+[[package]]
+name = "magnus"
+version = "0.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d87ae53030f3a22e83879e666cb94e58a7bdf31706878a0ba48752994146dab"
+dependencies = [
+ "magnus-macros",
+ "rb-sys",
+ "rb-sys-env",
+ "seq-macro",
+]
+
+[[package]]
+name = "magnus-macros"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5968c820e2960565f647819f5928a42d6e874551cab9d88d75e3e0660d7f71e3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "memchr"
+version = "2.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
+
+[[package]]
+name = "minimal-lexical"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68354c5c6bd36d73ff3feceb05efa59b6acb7626617f4962be322a825e61f79a"
+
+[[package]]
+name = "nom"
+version = "7.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d273983c5a657a70a3e8f2a01329822f3b8c8172b73826411a55751e404a0a4a"
+dependencies = [
+ "memchr",
+ "minimal-lexical",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rb-sys"
+version = "0.9.128"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "45ca28513560e56cfb79a62b1fce363c73af170a182024ce880c77ee9429920a"
+dependencies = [
+ "rb-sys-build",
+]
+
+[[package]]
+name = "rb-sys-build"
+version = "0.9.128"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce04b2c55eff3a21aaa623fcc655d94373238e72cac6b3e1a3641ff31649f99a"
+dependencies = [
+ "bindgen",
+ "lazy_static",
+ "proc-macro2",
+ "quote",
+ "regex",
+ "shell-words",
+ "syn",
+]
+
+[[package]]
+name = "rb-sys-env"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a35802679f07360454b418a5d1735c89716bde01d35b1560fc953c1415a0b3bb"
+
+[[package]]
+name = "regex"
+version = "1.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e10754a14b9137dd7b1e3e5b0493cc9171fdd105e0ab477f51b72e7f3ac0e276"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
+
+[[package]]
+name = "ruby_fst"
+version = "0.1.0"
+dependencies = [
+ "fst",
+ "magnus",
+ "rb-sys",
+]
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94300abf3f1ae2e2b8ffb7b58043de3d399c73fa6f4b73826402a5c457614dbe"
+
+[[package]]
+name = "seq-macro"
+version = "0.3.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc"
+
+[[package]]
+name = "shell-words"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc6fe69c597f9c37bfeeeeeb33da3530379845f10be461a66d16d03eca2ded77"
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "syn"
+version = "2.0.117"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "utf8-ranges"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7fcfc827f90e53a02eaef5e535ee14266c1d569214c6aa70133a624d8a3164ba"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"

data/Cargo.toml

@@ -0,0 +1,3 @@
+[workspace]
+resolver = "2"
+members = ["ext/ruby_fst"]

data/Gemfile

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'minitest', '~> 5.0'
+gem 'rake', '~> 13.0'
+gem 'rake-compiler', '~> 1.2'

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,126 @@
+# ruby-fst
+
+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, range queries, and fuzzy search.
+
+## Requirements
+
+- Ruby >= 3.0
+- Rust toolchain (for compilation)
+
+## Installation
+
+```ruby
+gem 'ruby-fst'
+```
+
+## Usage
+
+### Map
+
+Ordered map from byte string keys to unsigned 64-bit integer values. Keys must be inserted in lexicographic order.
+
+```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 }
+```
+
+### 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
+```
+
+This is useful for IP range lookups. Encode range starts as 4-byte big-endian keys and use `get_le` to find which range an IP falls into:
+
+```ruby
+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
+key, label_id = map.get_le([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.
+
+```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
+# To/from bytes
+bytes = map.to_bytes
+map = RubyFst::Map.new(bytes)
+
+# To/from file
+map.save('/path/to/file.fst')
+map = RubyFst::Map.from_path('/path/to/file.fst')
+```
+
+## Development
+
+```
+bundle install
+bundle exec rake compile test
+```
+
+## 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,44 @@
+# frozen_string_literal: true
+
+require 'rake/testtask'
+require 'rb_sys/extensiontask'
+
+GEMSPEC = Gem::Specification.load('ruby_fst.gemspec')
+
+RbSys::ExtensionTask.new('ruby_fst', GEMSPEC) do |ext|
+  ext.lib_dir = 'lib/ruby_fst'
+end
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: %i(compile test)
+
+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')
+
+  content = File.read(version_file)
+  current = content[/VERSION = '(.+)'/, 1]
+  major, minor, patch = current.split('.').map(&:to_i)
+
+  case level
+  when 'major' then major += 1; minor = 0; patch = 0
+  when 'minor' then minor += 1; patch = 0
+  when 'patch' then patch += 1
+  else abort("Unknown level: #{level}. Use major, minor, or patch.")
+  end
+
+  new_version = "#{major}.#{minor}.#{patch}"
+
+  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}\""))
+
+  puts("#{current} -> #{new_version}")
+end

data/ext/ruby_fst/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "ruby_fst"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+magnus = { version = "0.7", features = ["rb-sys"] }
+rb-sys = { version = "0.9", features = ["stable-api-compiled-fallback"] }
+fst = { version = "0.4", features = ["levenshtein"] }

data/ext/ruby_fst/extconf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'rb_sys/mkmf'
+
+create_rust_makefile('ruby_fst/ruby_fst')

data/ext/ruby_fst/src/lib.rs

@@ -0,0 +1,405 @@
+use std::cell::RefCell;
+use std::fs;
+
+use fst::automaton::Levenshtein;
+use fst::raw::{CompiledAddr, Fst, Node, Output};
+use fst::{IntoStreamer, Streamer};
+use magnus::prelude::*;
+use magnus::{block, exception, function, method, Error, RArray, RString, Ruby, Value};
+
+fn err(msg: impl std::fmt::Display) -> Error {
+    Error::new(exception::runtime_error(), msg.to_string())
+}
+
+fn ruby() -> Ruby {
+    unsafe { Ruby::get_unchecked() }
+}
+
+// ---------------------------------------------------------------------------
+// Map
+// ---------------------------------------------------------------------------
+
+#[magnus::wrap(class = "RubyFst::Map", free_immediately, size)]
+struct FstMap {
+    inner: fst::Map<Vec<u8>>,
+}
+
+impl FstMap {
+    fn new(bytes: RString) -> Result<Self, Error> {
+        let data = unsafe { bytes.as_slice() }.to_vec();
+        let inner = fst::Map::new(data).map_err(err)?;
+        Ok(Self { inner })
+    }
+
+    fn from_path(path: String) -> Result<Self, Error> {
+        let data = fs::read(&path).map_err(err)?;
+        let inner = fst::Map::new(data).map_err(err)?;
+        Ok(Self { inner })
+    }
+
+    fn get(&self, key: RString) -> Option<u64> {
+        let key = unsafe { key.as_slice() };
+        self.inner.get(key)
+    }
+
+    fn contains(&self, key: RString) -> bool {
+        let key = unsafe { key.as_slice() };
+        self.inner.contains_key(key)
+    }
+
+    fn len(&self) -> usize {
+        self.inner.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.inner.is_empty()
+    }
+
+    fn to_bytes(&self) -> RString {
+        ruby().str_from_slice(self.inner.as_fst().as_bytes())
+    }
+
+    fn save(&self, path: String) -> Result<(), Error> {
+        fs::write(&path, self.inner.as_fst().as_bytes()).map_err(err)
+    }
+
+    fn get_le(&self, key: RString) -> Result<Option<RArray>, Error> {
+        let r = ruby();
+        let key = unsafe { key.as_slice() };
+        match floor_lookup(self.inner.as_fst(), key) {
+            Some((found_key, value)) => {
+                let arr = r.ary_new_capa(2);
+                arr.push(r.str_from_slice(&found_key))?;
+                arr.push(value)?;
+                Ok(Some(arr))
+            }
+            None => Ok(None),
+        }
+    }
+
+    fn get_ge(&self, key: RString) -> Result<Option<RArray>, Error> {
+        let r = ruby();
+        let key = unsafe { key.as_slice() };
+        let mut stream = self.inner.range().ge(key).into_stream();
+        match stream.next() {
+            Some((k, v)) => {
+                let arr = r.ary_new_capa(2);
+                arr.push(r.str_from_slice(k))?;
+                arr.push(v)?;
+                Ok(Some(arr))
+            }
+            None => Ok(None),
+        }
+    }
+
+    fn each(&self) -> Result<(), Error> {
+        let r = ruby();
+        let mut stream = (&self.inner).into_stream();
+        while let Some((key, value)) = stream.next() {
+            let rb_key = r.str_from_slice(key);
+            let _: Value = block::yield_values((rb_key, value))?;
+        }
+        Ok(())
+    }
+
+    fn search_levenshtein(&self, query: String, distance: u32) -> Result<(), Error> {
+        let r = ruby();
+        let lev = Levenshtein::new(&query, distance).map_err(err)?;
+        let mut stream = self.inner.search(lev).into_stream();
+        while let Some((key, value)) = stream.next() {
+            let rb_key = r.str_from_slice(key);
+            let _: Value = block::yield_values((rb_key, value))?;
+        }
+        Ok(())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// MapBuilder
+// ---------------------------------------------------------------------------
+
+#[magnus::wrap(class = "RubyFst::MapBuilder", free_immediately, size)]
+struct FstMapBuilder {
+    inner: RefCell<Option<fst::MapBuilder<Vec<u8>>>>,
+}
+
+impl FstMapBuilder {
+    fn new() -> Self {
+        Self {
+            inner: RefCell::new(Some(fst::MapBuilder::memory())),
+        }
+    }
+
+    fn insert(&self, key: RString, value: u64) -> Result<(), Error> {
+        let key = unsafe { key.as_slice() }.to_vec();
+        let mut guard = self.inner.borrow_mut();
+        let b = guard.as_mut().ok_or_else(|| err("builder already finished"))?;
+        b.insert(&key, value).map_err(err)
+    }
+
+    fn finish(&self) -> Result<RString, Error> {
+        let mut guard = self.inner.borrow_mut();
+        let b = guard.take().ok_or_else(|| err("builder already finished"))?;
+        let bytes = b.into_inner().map_err(err)?;
+        Ok(ruby().str_from_slice(&bytes))
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Set
+// ---------------------------------------------------------------------------
+
+#[magnus::wrap(class = "RubyFst::Set", free_immediately, size)]
+struct FstSet {
+    inner: fst::Set<Vec<u8>>,
+}
+
+impl FstSet {
+    fn new(bytes: RString) -> Result<Self, Error> {
+        let data = unsafe { bytes.as_slice() }.to_vec();
+        let inner = fst::Set::new(data).map_err(err)?;
+        Ok(Self { inner })
+    }
+
+    fn from_path(path: String) -> Result<Self, Error> {
+        let data = fs::read(&path).map_err(err)?;
+        let inner = fst::Set::new(data).map_err(err)?;
+        Ok(Self { inner })
+    }
+
+    fn contains(&self, key: RString) -> bool {
+        let key = unsafe { key.as_slice() };
+        self.inner.contains(key)
+    }
+
+    fn len(&self) -> usize {
+        self.inner.len()
+    }
+
+    fn is_empty(&self) -> bool {
+        self.inner.is_empty()
+    }
+
+    fn to_bytes(&self) -> RString {
+        ruby().str_from_slice(self.inner.as_fst().as_bytes())
+    }
+
+    fn save(&self, path: String) -> Result<(), Error> {
+        fs::write(&path, self.inner.as_fst().as_bytes()).map_err(err)
+    }
+
+    fn each(&self) -> Result<(), Error> {
+        let r = ruby();
+        let mut stream = (&self.inner).into_stream();
+        while let Some(key) = stream.next() {
+            let rb_key = r.str_from_slice(key);
+            let _: Value = block::yield_value(rb_key)?;
+        }
+        Ok(())
+    }
+
+    fn search_levenshtein(&self, query: String, distance: u32) -> Result<(), Error> {
+        let r = ruby();
+        let lev = Levenshtein::new(&query, distance).map_err(err)?;
+        let mut stream = self.inner.search(lev).into_stream();
+        while let Some(key) = stream.next() {
+            let rb_key = r.str_from_slice(key);
+            let _: Value = block::yield_value(rb_key)?;
+        }
+        Ok(())
+    }
+}
+
+// ---------------------------------------------------------------------------
+// SetBuilder
+// ---------------------------------------------------------------------------
+
+#[magnus::wrap(class = "RubyFst::SetBuilder", free_immediately, size)]
+struct FstSetBuilder {
+    inner: RefCell<Option<fst::SetBuilder<Vec<u8>>>>,
+}
+
+impl FstSetBuilder {
+    fn new() -> Self {
+        Self {
+            inner: RefCell::new(Some(fst::SetBuilder::memory())),
+        }
+    }
+
+    fn insert(&self, key: RString) -> Result<(), Error> {
+        let key = unsafe { key.as_slice() }.to_vec();
+        let mut guard = self.inner.borrow_mut();
+        let b = guard.as_mut().ok_or_else(|| err("builder already finished"))?;
+        b.insert(&key).map_err(err)
+    }
+
+    fn finish(&self) -> Result<RString, Error> {
+        let mut guard = self.inner.borrow_mut();
+        let b = guard.take().ok_or_else(|| err("builder already finished"))?;
+        let bytes = b.into_inner().map_err(err)?;
+        Ok(ruby().str_from_slice(&bytes))
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Floor lookup (get_le): greatest key <= query
+// ---------------------------------------------------------------------------
+
+struct Frame {
+    node_addr: CompiledAddr,
+    output: Output,
+    prefix_len: usize,
+    max_lesser_idx: Option<usize>,
+    is_final: bool,
+    final_value: u64,
+}
+
+fn find_max_lesser(node: &Node, byte: u8) -> Option<usize> {
+    let n = node.len();
+    if n == 0 {
+        return None;
+    }
+    let mut lo: usize = 0;
+    let mut hi: usize = n;
+    while lo < hi {
+        let mid = lo + (hi - lo) / 2;
+        if node.transition(mid).inp < byte {
+            lo = mid + 1;
+        } else {
+            hi = mid;
+        }
+    }
+    lo.checked_sub(1)
+}
+
+fn rightmost_to_leaf<D: AsRef<[u8]>>(
+    fst: &Fst<D>,
+    addr: CompiledAddr,
+    output: Output,
+) -> (Vec<u8>, u64) {
+    let mut node = fst.node(addr);
+    let mut out = output;
+    let mut suffix = Vec::new();
+
+    while node.len() > 0 {
+        let last = node.len() - 1;
+        let t = node.transition(last);
+        suffix.push(t.inp);
+        out = out.cat(t.out);
+        node = fst.node(t.addr);
+    }
+
+    (suffix, out.cat(node.final_output()).value())
+}
+
+fn floor_lookup<D: AsRef<[u8]>>(fst: &Fst<D>, key: &[u8]) -> Option<(Vec<u8>, u64)> {
+    let root = fst.root();
+
+    if key.is_empty() {
+        return if root.is_final() {
+            Some((Vec::new(), root.final_output().value()))
+        } else {
+            None
+        };
+    }
+
+    let mut node = root;
+    let mut output = Output::zero();
+    let mut stack: Vec<Frame> = Vec::with_capacity(key.len());
+    let mut matched: usize = 0;
+
+    for &byte in key.iter() {
+        let lesser = find_max_lesser(&node, byte);
+
+        stack.push(Frame {
+            node_addr: node.addr(),
+            output,
+            prefix_len: matched,
+            max_lesser_idx: lesser,
+            is_final: node.is_final(),
+            final_value: output.cat(node.final_output()).value(),
+        });
+
+        match node.find_input(byte) {
+            Some(idx) => {
+                let t = node.transition(idx);
+                output = output.cat(t.out);
+                node = fst.node(t.addr);
+                matched += 1;
+            }
+            None => break,
+        }
+    }
+
+    if matched == key.len() && node.is_final() {
+        return Some((key.to_vec(), output.cat(node.final_output()).value()));
+    }
+
+    while let Some(frame) = stack.pop() {
+        if let Some(j) = frame.max_lesser_idx {
+            let frame_node = fst.node(frame.node_addr);
+            let t = frame_node.transition(j);
+            let mut result = key[..frame.prefix_len].to_vec();
+            result.push(t.inp);
+            let branch_output = frame.output.cat(t.out);
+            let (suffix, val) = rightmost_to_leaf(fst, t.addr, branch_output);
+            result.extend(suffix);
+            return Some((result, val));
+        }
+
+        if frame.is_final {
+            return Some((key[..frame.prefix_len].to_vec(), frame.final_value));
+        }
+    }
+
+    None
+}
+
+// ---------------------------------------------------------------------------
+// Init
+// ---------------------------------------------------------------------------
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), Error> {
+    let module = ruby.define_module("RubyFst")?;
+
+    let map_class = module.define_class("Map", ruby.class_object())?;
+    map_class.define_singleton_method("new", function!(FstMap::new, 1))?;
+    map_class.define_singleton_method("from_path", function!(FstMap::from_path, 1))?;
+    map_class.define_method("get", method!(FstMap::get, 1))?;
+    map_class.define_method("[]", method!(FstMap::get, 1))?;
+    map_class.define_method("contains?", method!(FstMap::contains, 1))?;
+    map_class.define_method("length", method!(FstMap::len, 0))?;
+    map_class.define_method("size", method!(FstMap::len, 0))?;
+    map_class.define_method("empty?", method!(FstMap::is_empty, 0))?;
+    map_class.define_method("to_bytes", method!(FstMap::to_bytes, 0))?;
+    map_class.define_method("save", method!(FstMap::save, 1))?;
+    map_class.define_method("get_le", method!(FstMap::get_le, 1))?;
+    map_class.define_method("get_ge", method!(FstMap::get_ge, 1))?;
+    map_class.define_method("each", method!(FstMap::each, 0))?;
+    map_class.define_method("search_levenshtein", method!(FstMap::search_levenshtein, 2))?;
+
+    let map_builder = module.define_class("MapBuilder", ruby.class_object())?;
+    map_builder.define_singleton_method("new", function!(FstMapBuilder::new, 0))?;
+    map_builder.define_method("insert", method!(FstMapBuilder::insert, 2))?;
+    map_builder.define_method("finish", method!(FstMapBuilder::finish, 0))?;
+
+    let set_class = module.define_class("Set", ruby.class_object())?;
+    set_class.define_singleton_method("new", function!(FstSet::new, 1))?;
+    set_class.define_singleton_method("from_path", function!(FstSet::from_path, 1))?;
+    set_class.define_method("contains?", method!(FstSet::contains, 1))?;
+    set_class.define_method("length", method!(FstSet::len, 0))?;
+    set_class.define_method("size", method!(FstSet::len, 0))?;
+    set_class.define_method("empty?", method!(FstSet::is_empty, 0))?;
+    set_class.define_method("to_bytes", method!(FstSet::to_bytes, 0))?;
+    set_class.define_method("save", method!(FstSet::save, 1))?;
+    set_class.define_method("each", method!(FstSet::each, 0))?;
+    set_class.define_method("search_levenshtein", method!(FstSet::search_levenshtein, 2))?;
+
+    let set_builder = module.define_class("SetBuilder", ruby.class_object())?;
+    set_builder.define_singleton_method("new", function!(FstSetBuilder::new, 0))?;
+    set_builder.define_method("insert", method!(FstSetBuilder::insert, 1))?;
+    set_builder.define_method("finish", method!(FstSetBuilder::finish, 0))?;
+
+    Ok(())
+}

data/lib/ruby_fst/version.rb

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

data/lib/ruby_fst.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'ruby_fst/version'
+require_relative 'ruby_fst/ruby_fst'
+
+module RubyFst
+  class Map
+    include Enumerable
+  end
+
+  class Set
+    include Enumerable
+  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.0'
+
+  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/releases'
+
+  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,71 @@
+--- !ruby/object:Gem::Specification
+name: ruby-fst
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Denis Sablic
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: Finite state transducer backed ordered sets and maps via the Rust fst
+  crate by BurntSushi
+email:
+- denis.sablic@gmail.com
+executables: []
+extensions:
+- ext/ruby_fst/extconf.rb
+extra_rdoc_files: []
+files:
+- Cargo.lock
+- Cargo.toml
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- ext/ruby_fst/Cargo.toml
+- ext/ruby_fst/extconf.rb
+- ext/ruby_fst/src/lib.rs
+- lib/ruby_fst.rb
+- 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/releases
+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: 3.6.9
+specification_version: 4
+summary: Ruby bindings for the Rust fst crate
+test_files: []