ruby-fst 0.1.0 → 0.2.0

checksums.yaml

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

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/Cargo.lock

@@ -115,9 +115,9 @@ dependencies = [
 
 [[package]]
 name = "magnus"
-version = "0.7.1"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3d87ae53030f3a22e83879e666cb94e58a7bdf31706878a0ba48752994146dab"
+checksum = "3b36a5b126bbe97eb0d02d07acfeb327036c6319fd816139a49824a83b7f9012"
 dependencies = [
  "magnus-macros",
  "rb-sys",
@@ -127,9 +127,9 @@ dependencies = [
 
 [[package]]
 name = "magnus-macros"
-version = "0.6.0"
+version = "0.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5968c820e2960565f647819f5928a42d6e874551cab9d88d75e3e0660d7f71e3"
+checksum = "47607461fd8e1513cb4f2076c197d8092d921a1ea75bd08af97398f593751892"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -142,6 +142,15 @@ version = "2.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79"
 
+[[package]]
+name = "memmap2"
+version = "0.9.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "714098028fe011992e1c3962653c96b2d578c4b4bce9036e15ff220319b1e0e3"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "minimal-lexical"
 version = "0.2.1"
@@ -202,9 +211,9 @@ dependencies = [
 
 [[package]]
 name = "rb-sys-env"
-version = "0.1.2"
+version = "0.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a35802679f07360454b418a5d1735c89716bde01d35b1560fc953c1415a0b3bb"
+checksum = "cca7ad6a7e21e72151d56fe2495a259b5670e204c3adac41ee7ef676ea08117a"
 
 [[package]]
 name = "regex"
@@ -237,10 +246,11 @@ checksum = "dc897dd8d9e8bd1ed8cdad82b5966c3e0ecae09fb1907d58efaa013543185d0a"
 
 [[package]]
 name = "ruby_fst"
-version = "0.1.0"
+version = "0.2.0"
 dependencies = [
  "fst",
  "magnus",
+ "memmap2",
  "rb-sys",
 ]
 

data/Gemfile

@@ -7,3 +7,6 @@ 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/README.md

@@ -1,23 +1,35 @@
 # 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.
+[![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.0
-- Rust toolchain (for compilation)
+- 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'
 ```
 
-## Usage
+## 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
+## Map
 
-Ordered map from byte string keys to unsigned 64-bit integer values. Keys must be inserted in lexicographic order.
+Ordered map from byte string keys to unsigned 64-bit integer values.
 
 ```ruby
 require 'ruby_fst'
@@ -28,15 +40,15 @@ 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['foo']             # => 1
+map.get('missing')     # => nil
+map.contains?('bar')   # => true
+map.length             # => 3
 
-map.each { |key, value| puts "#{key}: #{value}" }
+map.each { |key, value| puts("#{key}: #{value}") }
 ```
 
-### Set
+## Set
 
 Ordered set of byte string keys.
 
@@ -47,13 +59,30 @@ builder.insert('baz')
 builder.insert('foo')
 set = RubyFst::Set.new(builder.finish)
 
-set.contains?('foo') # => true
-set.length           # => 3
+set.contains?('foo')   # => true
+set.length             # => 3
 
-set.each { |key| puts key }
+set.each { |key| puts(key) }
 ```
 
-### Floor and ceiling lookups
+## 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`.
 
@@ -64,61 +93,80 @@ 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
+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` to find which range an IP falls into:
+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([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'))
+label_id = map.get_le_value([ip].pack('N'))
 ```
 
-### Levenshtein search
+## 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 }
+map.search_levenshtein('far', 1) { |key, value| puts(key) }
 # => bar
 ```
 
 Works on sets too:
 
 ```ruby
-set.search_levenshtein('university', 2) { |key| puts key }
+set.search_levenshtein('university', 2) { |key| puts(key) }
 ```
 
-### Serialization
+## Serialization
 
 ```ruby
-# To/from bytes
-bytes = map.to_bytes
+# Bytes
+bytes = map.to_bytes              # binary string
 map = RubyFst::Map.new(bytes)
 
-# To/from file
+# 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
+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.

data/Rakefile

@@ -2,11 +2,22 @@
 
 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|
@@ -14,31 +25,55 @@ Rake::TestTask.new do |t|
   t.test_files = FileList['test/**/*_test.rb']
 end
 
-task default: %i(compile test)
+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)
 
-  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}"
+  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/ext/ruby_fst/Cargo.toml

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

data/ext/ruby_fst/src/lib.rs

@@ -1,39 +1,105 @@
 use std::cell::RefCell;
-use std::fs;
+use std::fs::{self, File};
 
 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};
+use magnus::{function, method, Error, RArray, RString, Ruby, Value};
+use memmap2::Mmap;
 
 fn err(msg: impl std::fmt::Display) -> Error {
-    Error::new(exception::runtime_error(), msg.to_string())
+    Error::new(ruby().exception_runtime_error(), msg.to_string())
 }
 
+// SAFETY: every method exposed to Ruby is invoked by the VM on the GVL-owning
+// thread, so `Ruby::get_unchecked()` is sound — calling code must not invoke
+// this from a non-Ruby thread.
 fn ruby() -> Ruby {
     unsafe { Ruby::get_unchecked() }
 }
 
+// ---------------------------------------------------------------------------
+// Storage: backing buffer for an FST. Either an owned heap allocation or a
+// memory map. Both implement AsRef<[u8]> so fst::Map / fst::Set can accept
+// either without monomorphising the wrapper structs.
+// ---------------------------------------------------------------------------
+
+enum Storage {
+    Mem(Vec<u8>),
+    Mmap(Mmap),
+}
+
+impl AsRef<[u8]> for Storage {
+    fn as_ref(&self) -> &[u8] {
+        match self {
+            Storage::Mem(v) => v.as_ref(),
+            Storage::Mmap(m) => m.as_ref(),
+        }
+    }
+}
+
+fn read_storage(path: &str) -> Result<Storage, Error> {
+    let data = fs::read(path).map_err(err)?;
+    Ok(Storage::Mem(data))
+}
+
+fn mmap_storage(path: &str) -> Result<Storage, Error> {
+    let file = File::open(path).map_err(err)?;
+    // SAFETY: callers opt in to mmap and accept the contract that the file
+    // must not be modified or truncated while the FST is alive. We document
+    // this in the Ruby-level docs.
+    let mmap = unsafe { Mmap::map(&file) }.map_err(err)?;
+    Ok(Storage::Mmap(mmap))
+}
+
+// SAFETY for `RString::as_slice()` callers below: between obtaining the slice
+// and dropping it, no Ruby allocation, GC trigger, or string mutation occurs.
+// We either copy into a Vec immediately or pass the slice into pure-Rust fst
+// operations that never re-enter Ruby.
+
+fn rstring_to_vec(s: RString) -> Vec<u8> {
+    unsafe { s.as_slice() }.to_vec()
+}
+
+// Returns the exclusive upper bound for a prefix scan: the smallest byte
+// string strictly greater than `prefix` that does NOT have `prefix` as a
+// prefix. None when no such bound exists (empty prefix, or all-0xFF prefix);
+// the scan is then unbounded above.
+fn prefix_upper_bound(prefix: &[u8]) -> Option<Vec<u8>> {
+    let mut upper = prefix.to_vec();
+    while let Some(byte) = upper.last_mut() {
+        if *byte < 0xFF {
+            *byte += 1;
+            return Some(upper);
+        }
+        upper.pop();
+    }
+    None
+}
+
 // ---------------------------------------------------------------------------
 // Map
 // ---------------------------------------------------------------------------
 
 #[magnus::wrap(class = "RubyFst::Map", free_immediately, size)]
 struct FstMap {
-    inner: fst::Map<Vec<u8>>,
+    inner: fst::Map<Storage>,
 }
 
 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)?;
+        let inner = fst::Map::new(Storage::Mem(rstring_to_vec(bytes))).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)?;
+        let inner = fst::Map::new(read_storage(&path)?).map_err(err)?;
+        Ok(Self { inner })
+    }
+
+    fn from_path_mmap(path: String) -> Result<Self, Error> {
+        let inner = fst::Map::new(mmap_storage(&path)?).map_err(err)?;
         Ok(Self { inner })
     }
 
@@ -77,6 +143,11 @@ impl FstMap {
         }
     }
 
+    fn get_le_value(&self, key: RString) -> Option<u64> {
+        let key = unsafe { key.as_slice() };
+        floor_value(self.inner.as_fst(), key)
+    }
+
     fn get_ge(&self, key: RString) -> Result<Option<RArray>, Error> {
         let r = ruby();
         let key = unsafe { key.as_slice() };
@@ -92,12 +163,53 @@ impl FstMap {
         }
     }
 
+    fn get_ge_value(&self, key: RString) -> Option<u64> {
+        let key = unsafe { key.as_slice() };
+        let mut stream = self.inner.range().ge(key).into_stream();
+        stream.next().map(|(_, v)| v)
+    }
+
     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))?;
+            let _: Value = r.yield_values((rb_key, value))?;
+        }
+        Ok(())
+    }
+
+    fn range(&self, ge: Option<RString>, le: Option<RString>) -> Result<(), Error> {
+        let r = ruby();
+        let ge_bytes = ge.map(rstring_to_vec);
+        let le_bytes = le.map(rstring_to_vec);
+        let mut builder = self.inner.range();
+        if let Some(ref b) = ge_bytes {
+            builder = builder.ge(b);
+        }
+        if let Some(ref b) = le_bytes {
+            builder = builder.le(b);
+        }
+        let mut stream = builder.into_stream();
+        while let Some((key, value)) = stream.next() {
+            let rb_key = r.str_from_slice(key);
+            let _: Value = r.yield_values((rb_key, value))?;
+        }
+        Ok(())
+    }
+
+    fn starts_with(&self, prefix: RString) -> Result<(), Error> {
+        let r = ruby();
+        let prefix_bytes = rstring_to_vec(prefix);
+        let upper = prefix_upper_bound(&prefix_bytes);
+        let mut builder = self.inner.range().ge(&prefix_bytes);
+        if let Some(ref u) = upper {
+            builder = builder.lt(u);
+        }
+        let mut stream = builder.into_stream();
+        while let Some((key, value)) = stream.next() {
+            let rb_key = r.str_from_slice(key);
+            let _: Value = r.yield_values((rb_key, value))?;
         }
         Ok(())
     }
@@ -108,7 +220,7 @@ impl FstMap {
         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))?;
+            let _: Value = r.yield_values((rb_key, value))?;
         }
         Ok(())
     }
@@ -131,7 +243,7 @@ impl FstMapBuilder {
     }
 
     fn insert(&self, key: RString, value: u64) -> Result<(), Error> {
-        let key = unsafe { key.as_slice() }.to_vec();
+        let key = rstring_to_vec(key);
         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)
@@ -151,19 +263,22 @@ impl FstMapBuilder {
 
 #[magnus::wrap(class = "RubyFst::Set", free_immediately, size)]
 struct FstSet {
-    inner: fst::Set<Vec<u8>>,
+    inner: fst::Set<Storage>,
 }
 
 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)?;
+        let inner = fst::Set::new(Storage::Mem(rstring_to_vec(bytes))).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)?;
+        let inner = fst::Set::new(read_storage(&path)?).map_err(err)?;
+        Ok(Self { inner })
+    }
+
+    fn from_path_mmap(path: String) -> Result<Self, Error> {
+        let inner = fst::Set::new(mmap_storage(&path)?).map_err(err)?;
         Ok(Self { inner })
     }
 
@@ -193,7 +308,42 @@ impl FstSet {
         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)?;
+            let _: Value = r.yield_value(rb_key)?;
+        }
+        Ok(())
+    }
+
+    fn range(&self, ge: Option<RString>, le: Option<RString>) -> Result<(), Error> {
+        let r = ruby();
+        let ge_bytes = ge.map(rstring_to_vec);
+        let le_bytes = le.map(rstring_to_vec);
+        let mut builder = self.inner.range();
+        if let Some(ref b) = ge_bytes {
+            builder = builder.ge(b);
+        }
+        if let Some(ref b) = le_bytes {
+            builder = builder.le(b);
+        }
+        let mut stream = builder.into_stream();
+        while let Some(key) = stream.next() {
+            let rb_key = r.str_from_slice(key);
+            let _: Value = r.yield_value(rb_key)?;
+        }
+        Ok(())
+    }
+
+    fn starts_with(&self, prefix: RString) -> Result<(), Error> {
+        let r = ruby();
+        let prefix_bytes = rstring_to_vec(prefix);
+        let upper = prefix_upper_bound(&prefix_bytes);
+        let mut builder = self.inner.range().ge(&prefix_bytes);
+        if let Some(ref u) = upper {
+            builder = builder.lt(u);
+        }
+        let mut stream = builder.into_stream();
+        while let Some(key) = stream.next() {
+            let rb_key = r.str_from_slice(key);
+            let _: Value = r.yield_value(rb_key)?;
         }
         Ok(())
     }
@@ -204,7 +354,7 @@ impl FstSet {
         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)?;
+            let _: Value = r.yield_value(rb_key)?;
         }
         Ok(())
     }
@@ -227,7 +377,7 @@ impl FstSetBuilder {
     }
 
     fn insert(&self, key: RString) -> Result<(), Error> {
-        let key = unsafe { key.as_slice() }.to_vec();
+        let key = rstring_to_vec(key);
         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)
@@ -242,7 +392,13 @@ impl FstSetBuilder {
 }
 
 // ---------------------------------------------------------------------------
-// Floor lookup (get_le): greatest key <= query
+// Floor lookup (get_le): greatest key <= query.
+//
+// The upstream fst crate exposes `range().ge(...)` natively but not a floor
+// operation, so this walks the FST manually: descend matching the query while
+// recording, at each step, the rightmost transition strictly less than the
+// current query byte. If exact match fails we backtrack to the most recent
+// such transition and follow the rightmost path to a leaf.
 // ---------------------------------------------------------------------------
 
 struct Frame {
@@ -281,7 +437,7 @@ fn rightmost_to_leaf<D: AsRef<[u8]>>(
     let mut out = output;
     let mut suffix = Vec::new();
 
-    while node.len() > 0 {
+    while !node.is_empty() {
         let last = node.len() - 1;
         let t = node.transition(last);
         suffix.push(t.inp);
@@ -292,6 +448,20 @@ fn rightmost_to_leaf<D: AsRef<[u8]>>(
     (suffix, out.cat(node.final_output()).value())
 }
 
+fn rightmost_value<D: AsRef<[u8]>>(fst: &Fst<D>, addr: CompiledAddr, output: Output) -> u64 {
+    let mut node = fst.node(addr);
+    let mut out = output;
+
+    while !node.is_empty() {
+        let last = node.len() - 1;
+        let t = node.transition(last);
+        out = out.cat(t.out);
+        node = fst.node(t.addr);
+    }
+
+    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();
 
@@ -355,6 +525,65 @@ fn floor_lookup<D: AsRef<[u8]>>(fst: &Fst<D>, key: &[u8]) -> Option<(Vec<u8>, u6
     None
 }
 
+fn floor_value<D: AsRef<[u8]>>(fst: &Fst<D>, key: &[u8]) -> Option<u64> {
+    let root = fst.root();
+
+    if key.is_empty() {
+        return if root.is_final() {
+            Some(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(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 branch_output = frame.output.cat(t.out);
+            return Some(rightmost_value(fst, t.addr, branch_output));
+        }
+
+        if frame.is_final {
+            return Some(frame.final_value);
+        }
+    }
+
+    None
+}
+
 // ---------------------------------------------------------------------------
 // Init
 // ---------------------------------------------------------------------------
@@ -366,6 +595,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     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_singleton_method("from_path_mmap", function!(FstMap::from_path_mmap, 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))?;
@@ -375,8 +605,12 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     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_le_value", method!(FstMap::get_le_value, 1))?;
     map_class.define_method("get_ge", method!(FstMap::get_ge, 1))?;
+    map_class.define_method("get_ge_value", method!(FstMap::get_ge_value, 1))?;
     map_class.define_method("each", method!(FstMap::each, 0))?;
+    map_class.define_method("range", method!(FstMap::range, 2))?;
+    map_class.define_method("starts_with", method!(FstMap::starts_with, 1))?;
     map_class.define_method("search_levenshtein", method!(FstMap::search_levenshtein, 2))?;
 
     let map_builder = module.define_class("MapBuilder", ruby.class_object())?;
@@ -387,6 +621,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     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_singleton_method("from_path_mmap", function!(FstSet::from_path_mmap, 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))?;
@@ -394,6 +629,8 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     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("range", method!(FstSet::range, 2))?;
+    set_class.define_method("starts_with", method!(FstSet::starts_with, 1))?;
     set_class.define_method("search_levenshtein", method!(FstSet::search_levenshtein, 2))?;
 
     let set_builder = module.define_class("SetBuilder", ruby.class_object())?;

data/lib/ruby_fst/version.rb

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

data/lib/ruby_fst.rb

@@ -4,11 +4,37 @@ 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

@@ -11,11 +11,11 @@ Gem::Specification.new do |spec|
   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.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/releases'
+  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') }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-fst
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Denis Sablic
@@ -32,6 +32,8 @@ extensions:
 - ext/ruby_fst/extconf.rb
 extra_rdoc_files: []
 files:
+- ".rubocop.yml"
+- CHANGELOG.md
 - Cargo.lock
 - Cargo.toml
 - Gemfile
@@ -50,7 +52,7 @@ licenses:
 metadata:
   rubygems_mfa_required: 'true'
   source_code_uri: https://github.com/dsablic/ruby-fst
-  changelog_uri: https://github.com/dsablic/ruby-fst/releases
+  changelog_uri: https://github.com/dsablic/ruby-fst/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -58,7 +60,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="