fast_regexp 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea6096017d3c6747b5efdd80ac2a1c0feb0eff1b90653cb0b24f5e74295bea75
-  data.tar.gz: f22d78881e171014dcd8e02dd2918157faf4bbc0bd36fb9ae86f183ffb8db2cd
+  metadata.gz: 3512de3c64b392ae48a21422dc3e61423af58ddd4c8141e952a23c80799c2261
+  data.tar.gz: cd09cfa3f3299812e19bc043da29f814c340342af4434981b4a47a9cbb7eab53
 SHA512:
-  metadata.gz: 83407af617e35aa7892c4b05650304389644d415dfb442b6cc3352bd9c31a2d1c88348f4d74d499f7437ee322404f841b33008ac96eb1cd9685526e3bd8770e8
-  data.tar.gz: 919e759dc7b9d9ba21071b9a3e093ef3e0b32fd3bebfc9597650d753b9c40952fed2e401710a603f02aa116314bfb71935158852593a87b421f1b795b9d45caf
+  metadata.gz: e83cb56946505a54ce6511b0755ecfea0838268f79b51daf26f081490130f4db8049e561d37d136e1666536b10b24b555e7e005889e0d19fba6adca01b3bcc2e
+  data.tar.gz: 5f10f02b3fa5accab0732be061bca6c1ea0d5739c72dfa52485cd7306685792d129ba14e0e881a3aa27563347428dc367a725b829a9d493c0cdb9d92dc0f21cd

data/Cargo.lock

@@ -72,7 +72,6 @@ name = "fast_regexp"
 version = "0.1.0"
 dependencies = [
  "magnus",
- "rb-sys",
  "regex",
 ]
 

data/README.md

@@ -3,7 +3,9 @@
 [![Gem Version](https://badge.fury.io/rb/fast_regexp.svg)](https://badge.fury.io/rb/fast_regexp)
 [![Test](https://github.com/jetpks/fast_regexp/workflows/CI/badge.svg)](https://github.com/jetpks/fast_regexp/actions)
 
-Ruby bindings for [rust/regex](https://docs.rs/regex/latest/regex/) library.
+Fast, drop-in regex for Ruby — backed by [rust/regex](https://docs.rs/regex/latest/regex/) with transparent fallback to the stdlib `::Regexp` engine for features rust/regex doesn't support (lookaround, backreferences, possessive quantifiers, etc.).
+
+You get rust/regex's speed on the common path, and a single uniform API (`Fast::Regexp`, `Fast::Regexp::MatchData`) regardless of which engine actually ran underneath.
 
 ## Installation
 
@@ -128,11 +130,50 @@ Fast::Regexp.new('(?P<n>\w+)').names        # => ["n"]
 Fast::Regexp.new('(a)(b)').captures_count   # => 2
 ```
 
+### Engine fallback
+
+rust/regex doesn't support lookaround, backreferences, or possessive
+quantifiers. Rather than make you manage two regex libraries, `Fast::Regexp`
+silently falls back to stdlib `::Regexp` when it sees something rust/regex
+can't compile. The public API (`#match`, `#sub`, `#gsub`, `#===`, `#=~`,
+`MatchData`) is identical on both paths, so callers don't have to care which
+engine ran — but you can inspect or reach the underlying object when you
+need to:
+
+```ruby
+fast = Fast::Regexp.new('\w+')
+fast.fast?       # => true
+fast.native      # => #<Fast::Regexp::Native ...>  (rust-backed)
+
+slow = Fast::Regexp.new('foo(?=bar)')   # lookahead — rust/regex rejects
+slow.stdlib?     # => true
+slow.stdlib      # => /foo(?=bar)/  (the real ::Regexp)
+slow.match?("foobar")  # => true
+```
+
+`Fast::Regexp::MatchData` exposes the same `#native?` / `#stdlib?` / `#native`
+/ `#stdlib` accessors. Replacement templates use rust/regex syntax (`$1`,
+`${name}`, `$$`) on both paths; the stdlib fallback translates them for you.
+
+You can force a specific engine via the `backend:` kwarg:
+
+```ruby
+Fast::Regexp.new('\w+', backend: :fast)     # rust/regex only; raises on unsupported
+Fast::Regexp.new(pat,   backend: :stdlib)   # skip rust/regex; use ::Regexp directly
+Fast::Regexp.new('\w+', backend: :auto)     # default — try rust, fall back on reject
+```
+
+> [!NOTE]
+> The fast path is byte-based (rust/regex's `regex::bytes`), so `#=~` returns
+> a *byte* offset. The stdlib fallback path returns the byte offset too, for
+> API consistency.
+
 > [!WARNING]
-> `rust/regex` regular expression syntax differs from Ruby's built-in
-> [`Regexp`](https://docs.ruby-lang.org/en/3.4/Regexp.html) library, see the
-> [official syntax page](https://docs.rs/regex/latest/regex/index.html#syntax) for more
-> details.
+> `rust/regex` syntax differs from Ruby's built-in
+> [`Regexp`](https://docs.ruby-lang.org/en/3.4/Regexp.html) — see the
+> [rust/regex syntax page](https://docs.rs/regex/latest/regex/index.html#syntax).
+> When fallback kicks in, your pattern is interpreted by stdlib `::Regexp`
+> instead, so Ruby's syntax applies for that compile.
 
 ### Searching simultaneously
 
@@ -176,11 +217,11 @@ It also supports parsing of strings with invalid UTF-8 characters by default. It
 In case unicode awarness of matchers should be disabled, both `Fast::Regexp` and `Fast::Regexp::Set` support `unicode: false` option:
 
 ```ruby
-Fast::Regexp.new('\w+').match('ю٤夏')
-# => ["ю٤夏"]
+Fast::Regexp.new('\w+').match('ю٤夏')[0]
+# => "ю٤夏"
 
 Fast::Regexp.new('\w+', unicode: false).match('ю٤夏')
-# => []
+# => nil
 
 Fast::Regexp::Set.new(['\w', '\d', '\s']).match("ю٤\u2000")
 # => [0, 1, 2]
@@ -189,6 +230,16 @@ Fast::Regexp::Set.new(['\w', '\d', '\s'], unicode: false).match("ю٤\u2000")
 # => []
 ```
 
+## Documentation
+
+In-depth docs live under [`docs/`](docs/README.md), organized via the
+[Diátaxis](https://diataxis.fr/) framework:
+
+- **Tutorial:** [Getting started](docs/tutorials/getting-started.md)
+- **How-to:** [Migrate from stdlib `::Regexp`](docs/how-to/migrate-from-stdlib-regexp.md), [Handle unsupported syntax](docs/how-to/handle-unsupported-syntax.md)
+- **Reference:** [`Fast::Regexp`](docs/reference/fast-regexp.md), [`MatchData`](docs/reference/fast-regexp-matchdata.md), [`Set`](docs/reference/fast-regexp-set.md)
+- **Explainers:** [Engine fallback](docs/explainers/engine-fallback.md)
+
 ## Development
 
 ```sh
@@ -209,8 +260,8 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/jetpks
 huge thanks for the original bindings and the clean magnus integration that
 made this work easy to extend. This fork rebrands the gem, reshapes the
 public API (`Fast::Regexp`, real `MatchData`, `sub`/`gsub`, `===`/`=~`,
-`Regexp`-constructor coercion), and releases the GVL around regex execution
-for thread/fiber-friendly matching.
+`Regexp`-constructor coercion), and adds transparent fallback to stdlib
+`::Regexp` for patterns rust/regex can't compile.
 
 ## License
 

data/ext/fast_regexp/Cargo.toml

@@ -9,4 +9,3 @@ crate-type = ["cdylib"]
 [dependencies]
 magnus = "0.8"
 regex = "1"
-rb-sys = "0.9"

data/ext/fast_regexp/src/lib.rs

@@ -2,71 +2,13 @@ use magnus::{
     function, method,
     scan_args::{get_kwargs, scan_args},
     value::ReprValue,
-    Error, Module, Object, RArray, RHash, RString, Ruby, Symbol, TryConvert, Value,
+    Error, Module, Object, RArray, RClass, RHash, RString, Ruby, Symbol, TryConvert, Value,
 };
 use regex::bytes::{NoExpand, Regex, RegexBuilder, RegexSet, RegexSetBuilder};
 use std::collections::HashMap;
-use std::ffi::c_void;
-use std::ptr;
 use std::sync::Arc;
 
-/// Skip GVL release for haystacks smaller than this — the release/reacquire
-/// overhead (~µs) dwarfs the cost of a regex match on a tiny string.
-const GVL_RELEASE_THRESHOLD: usize = 1024;
-
-/// Run `func` with the GVL released so other Ruby threads (and the fiber
-/// scheduler on its host thread) can make progress during a long regex match.
-///
-/// The callback runs on the same OS thread — `Send` is not required, and the
-/// borrow checker enforces that any references stay valid for the call.
-fn without_gvl<F, R>(func: F) -> R
-where
-    F: FnOnce() -> R,
-{
-    struct Pack<F, R> {
-        func: Option<F>,
-        result: Option<R>,
-    }
-
-    unsafe extern "C" fn trampoline<F, R>(data: *mut c_void) -> *mut c_void
-    where
-        F: FnOnce() -> R,
-    {
-        let pack = &mut *(data as *mut Pack<F, R>);
-        let func = pack.func.take().expect("trampoline called twice");
-        pack.result = Some(func());
-        ptr::null_mut()
-    }
-
-    let mut pack: Pack<F, R> = Pack {
-        func: Some(func),
-        result: None,
-    };
-    unsafe {
-        rb_sys::rb_thread_call_without_gvl(
-            Some(trampoline::<F, R>),
-            &mut pack as *mut _ as *mut c_void,
-            None,
-            ptr::null_mut(),
-        );
-    }
-    pack.result.take().expect("callback did not run")
-}
-
-fn run_regex<F, R>(haystack_len: usize, func: F) -> R
-where
-    F: FnOnce() -> R,
-{
-    if haystack_len >= GVL_RELEASE_THRESHOLD {
-        without_gvl(func)
-    } else {
-        func()
-    }
-}
-
 fn haystack_bytes(haystack: &RString) -> Vec<u8> {
-    // Copy out of the Ruby heap so the bytes are safe to read after the GVL is
-    // released (Ruby 4's compacting GC can otherwise move the string).
     unsafe { haystack.as_slice() }.to_vec()
 }
 
@@ -126,7 +68,7 @@ impl RegexInner {
     }
 }
 
-#[magnus::wrap(class = "Fast::Regexp", free_immediately, size)]
+#[magnus::wrap(class = "Fast::Regexp::Native", free_immediately, size)]
 pub struct FastRegexp(Arc<RegexInner>);
 
 impl FastRegexp {
@@ -157,12 +99,10 @@ impl FastRegexp {
         let regex = &self.0.regex;
         let bytes = haystack_bytes(&haystack);
 
-        let offsets = run_regex(bytes.len(), || {
-            regex.captures(&bytes).map(|caps| {
-                (0..regex.captures_len())
-                    .map(|i| caps.get(i).map(|m| (m.start(), m.end())))
-                    .collect::<Vec<_>>()
-            })
+        let offsets = regex.captures(&bytes).map(|caps| {
+            (0..regex.captures_len())
+                .map(|i| caps.get(i).map(|m| (m.start(), m.end())))
+                .collect::<Vec<_>>()
         })?;
 
         Some(self.build_match_data(Arc::new(bytes), offsets))
@@ -173,29 +113,25 @@ impl FastRegexp {
         let bytes = haystack_bytes(&haystack);
 
         if regex.captures_len() == 1 {
-            let ranges: Vec<(usize, usize)> = run_regex(bytes.len(), || {
-                regex
-                    .find_iter(&bytes)
-                    .map(|m| (m.start(), m.end()))
-                    .collect()
-            });
+            let ranges: Vec<(usize, usize)> = regex
+                .find_iter(&bytes)
+                .map(|m| (m.start(), m.end()))
+                .collect();
             let result = ruby.ary_new_capa(ranges.len());
             for (s, e) in ranges {
                 result.push(utf8_string(ruby, &bytes[s..e]))?;
             }
             Ok(result)
         } else {
-            let groups: Vec<Vec<CaptureOffset>> = run_regex(bytes.len(), || {
-                regex
-                    .captures_iter(&bytes)
-                    .map(|caps| {
-                        caps.iter()
-                            .skip(1)
-                            .map(|c| c.map(|m| (m.start(), m.end())))
-                            .collect()
-                    })
-                    .collect()
-            });
+            let groups: Vec<Vec<CaptureOffset>> = regex
+                .captures_iter(&bytes)
+                .map(|caps| {
+                    caps.iter()
+                        .skip(1)
+                        .map(|c| c.map(|m| (m.start(), m.end())))
+                        .collect()
+                })
+                .collect();
             let result = ruby.ary_new_capa(groups.len());
             for group_ranges in groups {
                 let group = ruby.ary_new_capa(group_ranges.len());
@@ -216,16 +152,14 @@ impl FastRegexp {
         let bytes = haystack_bytes(&haystack);
         let n_groups = regex.captures_len();
 
-        let all: Vec<Vec<CaptureOffset>> = run_regex(bytes.len(), || {
-            regex
-                .captures_iter(&bytes)
-                .map(|caps| {
-                    (0..n_groups)
-                        .map(|i| caps.get(i).map(|m| (m.start(), m.end())))
-                        .collect()
-                })
-                .collect()
-        });
+        let all: Vec<Vec<CaptureOffset>> = regex
+            .captures_iter(&bytes)
+            .map(|caps| {
+                (0..n_groups)
+                    .map(|i| caps.get(i).map(|m| (m.start(), m.end())))
+                    .collect()
+            })
+            .collect();
 
         let shared = Arc::new(bytes);
         let result = ruby.ary_new_capa(all.len());
@@ -238,7 +172,7 @@ impl FastRegexp {
     pub fn is_match(&self, haystack: RString) -> bool {
         let regex = &self.0.regex;
         let bytes = haystack_bytes(&haystack);
-        run_regex(bytes.len(), || regex.is_match(&bytes))
+        regex.is_match(&bytes)
     }
 
     pub fn sub_str(
@@ -251,13 +185,11 @@ impl FastRegexp {
         let regex = &rb_self.0.regex;
         let bytes = haystack_bytes(&haystack);
         let repl = haystack_bytes(&replacement);
-        let out = run_regex(bytes.len(), || -> Vec<u8> {
-            if literal {
-                regex.replace(&bytes, NoExpand(&repl)).into_owned()
-            } else {
-                regex.replace(&bytes, &repl[..]).into_owned()
-            }
-        });
+        let out: Vec<u8> = if literal {
+            regex.replace(&bytes, NoExpand(&repl)).into_owned()
+        } else {
+            regex.replace(&bytes, &repl[..]).into_owned()
+        };
         utf8_string(ruby, &out)
     }
 
@@ -271,13 +203,11 @@ impl FastRegexp {
         let regex = &rb_self.0.regex;
         let bytes = haystack_bytes(&haystack);
         let repl = haystack_bytes(&replacement);
-        let out = run_regex(bytes.len(), || -> Vec<u8> {
-            if literal {
-                regex.replace_all(&bytes, NoExpand(&repl)).into_owned()
-            } else {
-                regex.replace_all(&bytes, &repl[..]).into_owned()
-            }
-        });
+        let out: Vec<u8> = if literal {
+            regex.replace_all(&bytes, NoExpand(&repl)).into_owned()
+        } else {
+            regex.replace_all(&bytes, &repl[..]).into_owned()
+        };
         utf8_string(ruby, &out)
     }
 
@@ -299,7 +229,7 @@ impl FastRegexp {
     }
 }
 
-#[magnus::wrap(class = "Fast::Regexp::MatchData", free_immediately, size)]
+#[magnus::wrap(class = "Fast::Regexp::Native::MatchData", free_immediately, size)]
 pub struct FastMatchData {
     haystack: Arc<Vec<u8>>,
     /// Index 0 is the whole match. Subsequent entries are capture groups in
@@ -482,13 +412,13 @@ impl FastRegexpSet {
     pub fn matches(&self, haystack: RString) -> Vec<usize> {
         let set = &self.0;
         let bytes = haystack_bytes(&haystack);
-        run_regex(bytes.len(), || set.matches(&bytes).iter().collect())
+        set.matches(&bytes).iter().collect()
     }
 
     pub fn is_match(&self, haystack: RString) -> bool {
         let set = &self.0;
         let bytes = haystack_bytes(&haystack);
-        run_regex(bytes.len(), || set.is_match(&bytes))
+        set.is_match(&bytes)
     }
 
     pub fn patterns(&self) -> Vec<String> {
@@ -499,8 +429,12 @@ impl FastRegexpSet {
 #[magnus::init]
 pub fn init(ruby: &Ruby) -> Result<(), Error> {
     let object_class = ruby.class_object();
-    let fast_module = ruby.define_module("Fast")?;
-    let regexp_class = fast_module.define_class("Regexp", object_class)?;
+    // Fast::Regexp must already be defined as a class by lib/fast_regexp.rb
+    // before this extension is required — the Ruby façade owns that constant
+    // and delegates to the Native class registered below.
+    let fast_module: magnus::RModule = object_class.const_get("Fast")?;
+    let regexp_facade: RClass = fast_module.const_get("Regexp")?;
+    let regexp_class = regexp_facade.define_class("Native", object_class)?;
 
     regexp_class.define_singleton_method("_native_new", function!(FastRegexp::new, -1))?;
     regexp_class.define_method("_native_match", method!(FastRegexp::rmatch, 1))?;
@@ -531,7 +465,8 @@ pub fn init(ruby: &Ruby) -> Result<(), Error> {
     match_data_class.define_method("byte_end", method!(FastMatchData::byte_end, 1))?;
     match_data_class.define_method("inspect", method!(FastMatchData::inspect, 0))?;
 
-    let regexp_set_class = regexp_class.define_class("Set", object_class)?;
+    // Set stays at Fast::Regexp::Set (no fallback; rust/regex RegexSet is the only backend).
+    let regexp_set_class = regexp_facade.define_class("Set", object_class)?;
 
     regexp_set_class.define_singleton_method("new", function!(FastRegexpSet::new, -1))?;
     regexp_set_class.define_method("match", method!(FastRegexpSet::matches, 1))?;

data/lib/fast_regexp/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   class Regexp
-    VERSION = "0.4.0"
+    VERSION = "0.6.0"
   end
 end

data/lib/fast_regexp.rb

@@ -1,12 +1,22 @@
 # frozen_string_literal: true
 
 require_relative "fast_regexp/version"
+
+module Fast
+  # Façade over rust/regex with a transparent fallback to stdlib `::Regexp`.
+  #
+  # `Fast::Regexp.new(pattern)` first tries to compile with rust/regex (fast,
+  # byte-based). If the pattern uses features rust/regex does not support
+  # (lookaround, backreferences, possessive quantifiers, etc.) we fall back
+  # to `::Regexp` so consumers don't have to juggle two libraries.
+  class Regexp
+  end
+end
+
+# Load the native extension AFTER the Fast::Regexp class shell exists — the
+# Rust init() looks up Fast::Regexp and registers Native under it.
 require_relative "fast_regexp/fast_regexp"
 
-# Ruby-side conveniences on top of the Rust extension. The native class only
-# exposes raw primitives (`_native_new`, `_native_match`, `_native_sub`,
-# `_native_gsub`); everything user-facing lives here so the API can grow
-# without touching FFI.
 module Fast
   class Regexp
     RUBY_FLAG_MAP = {
@@ -16,14 +26,21 @@ module Fast
     }.freeze
 
     class << self
-      # Accept either a pattern string or an existing `::Regexp`. When given a
-      # Regexp the flags (`/i`, `/x`, `/m`) are translated into a leading
-      # inline group so the rust/regex engine sees them. Unsupported features
-      # (lookaround, backrefs) still raise from the engine with a clear
-      # message.
+      # Compile a pattern. Accepts a String or a `::Regexp` (flags are
+      # translated into a leading `(?...)` group so rust/regex sees them).
+      # Falls back to `::Regexp` if rust/regex rejects the pattern.
       def new(pattern, **opts)
-        pattern = translate_regexp(pattern) if pattern.is_a?(::Regexp)
-        _native_new(pattern, **opts)
+        translated = pattern.is_a?(::Regexp) ? translate_regexp(pattern) : pattern
+        allocate.tap { |re| re.send(:initialize, translated, original: pattern, **opts) }
+      end
+
+      # Bulk-compile a symbol-keyed hash of patterns. Handy for defining a set
+      # of regex constants in one shot:
+      #
+      #   RE = Fast::Regexp.create_many(word: '\w+', num: '\d+').freeze
+      #   RE[:word].match("hello")
+      def create_many(**patterns)
+        patterns.transform_values { |pat| new(pat) }
       end
 
       private
@@ -36,34 +53,66 @@ module Fast
       end
     end
 
-    # Returns a `Fast::Regexp::MatchData` on hit, `nil` on miss — matching
-    # Ruby's `Regexp#match` shape so the old `[]`-truthy-but-empty trap is
-    # gone.
+    attr_reader :pattern, :backend
+
+    BACKENDS = %i[auto fast stdlib].freeze
+
+    # Internal — use `Fast::Regexp.new`. `original` is the unmodified input
+    # (String or ::Regexp) so we can build an accurate stdlib fallback.
+    # `backend:` forces a specific engine: `:auto` (default) tries rust/regex
+    # and falls back to stdlib, `:fast` raises if rust/regex rejects the
+    # pattern, `:stdlib` skips rust/regex entirely.
+    def initialize(pattern, original: pattern, backend: :auto, **opts)
+      raise ArgumentError, "backend must be one of #{BACKENDS.inspect}" unless BACKENDS.include?(backend)
+      @pattern = pattern
+      @backend = compile_backend(pattern, original, backend, opts)
+    end
+
+    def fast? = @backend.is_a?(Native)
+    def stdlib? = !fast?
+
+    # Escape hatches for callers that need the underlying object directly.
+    def native = fast? ? @backend : nil
+    def stdlib = stdlib? ? @backend : nil
+
     def match(haystack)
-      _native_match(coerce_string(haystack))
+      haystack = coerce_string(haystack)
+      raw = fast? ? @backend._native_match(haystack) : @backend.match(haystack)
+      raw && MatchData.new(raw, haystack)
+    end
+
+    def match?(haystack)
+      @backend.match?(coerce_string(haystack))
     end
 
-    # Case-equality. Enables `case/when` and RSpec's
-    # `expect(str).to match(re)`.
     def ===(other)
       return false unless other.respond_to?(:to_str)
       match?(other.to_str)
     end
 
-    # Returns the byte offset of the first match, or nil. Matches the
-    # semantics of `Regexp#=~` except positions are in **bytes** (rust/regex
-    # is byte-based).
+    # Byte offset of the first match (rust/regex is byte-based; stdlib path
+    # also returns bytes here for API consistency).
     def =~(other)
       return nil unless other.respond_to?(:to_str)
       m = match(other.to_str)
       m && m.byte_begin(0)
     end
 
-    # `sub(haystack, replacement)` or `sub(haystack) { |m| ... }`.
-    #
-    # The string form uses rust/regex's native replacement template: `$1`,
-    # `${name}`, `$$` for a literal `$`. To pass a replacement string that
-    # contains `$` literally, pass `literal: true`.
+    def scan(haystack)
+      @backend.scan(coerce_string(haystack))
+    end
+
+    def scan_matches(haystack)
+      haystack = coerce_string(haystack)
+      if fast?
+        @backend.scan_matches(haystack).map { |m| MatchData.new(m, haystack) }
+      else
+        results = []
+        haystack.scan(@backend) { results << MatchData.new(::Regexp.last_match, haystack) }
+        results
+      end
+    end
+
     def sub(haystack, replacement = nil, literal: false, &block)
       haystack = coerce_string(haystack)
       if block
@@ -73,32 +122,123 @@ module Fast
         "#{m.pre_match}#{block.call(m)}#{m.post_match}"
       else
         raise ArgumentError, "wrong number of arguments (given 1, expected 2)" if replacement.nil?
-        _native_sub(haystack, coerce_string(replacement), literal)
+        replacement = coerce_string(replacement)
+        if fast?
+          @backend._native_sub(haystack, replacement, literal)
+        else
+          haystack.sub(@backend, stdlib_replacement(replacement, literal))
+        end
       end
     end
 
-    # `gsub(haystack, replacement)` or `gsub(haystack) { |m| ... }`. See
-    # `#sub` for the template syntax.
     def gsub(haystack, replacement = nil, literal: false, &block)
       haystack = coerce_string(haystack)
       if block
         raise ArgumentError, "wrong number of arguments (given 2, expected 1 with block)" if replacement
-        gsub_with_block(haystack, &block)
+        fast? ? fast_gsub_with_block(haystack, &block) : stdlib_gsub_with_block(haystack, &block)
       else
         raise ArgumentError, "wrong number of arguments (given 1, expected 2)" if replacement.nil?
-        _native_gsub(haystack, coerce_string(replacement), literal)
+        replacement = coerce_string(replacement)
+        if fast?
+          @backend._native_gsub(haystack, replacement, literal)
+        else
+          haystack.gsub(@backend, stdlib_replacement(replacement, literal))
+        end
       end
     end
 
-    def inspect
-      "#<Fast::Regexp #{pattern.inspect}>"
+    # On the fast path this comes from rust/regex directly. On the stdlib
+    # fallback we walk the source counting capturing groups while honoring
+    # escapes, character classes, and non-capturing / lookaround prefixes.
+    def captures_count
+      return @backend.captures_count if fast?
+      count_stdlib_captures(@backend.source)
     end
 
+    def names
+      @backend.names
+    end
+
+    def inspect = "#<Fast::Regexp #{@pattern.inspect}#{stdlib? ? " (stdlib)" : ""}>"
     alias_method :to_s, :pattern
 
     private
 
-    def gsub_with_block(haystack)
+    def count_stdlib_captures(source)
+      count = 0
+      i = 0
+      len = source.length
+      while i < len
+        c = source[i]
+        if c == "\\"
+          i += 2
+        elsif c == "["
+          i += 1
+          i += 1 while i < len && source[i] != "]"
+          i += 1
+        elsif c == "("
+          # Capturing unless followed by (?:, (?=, (?!, (?#, (?<=, (?<!.
+          prefix = source[i + 1, 4] || ""
+          if prefix.start_with?("?:") || prefix.start_with?("?=") || prefix.start_with?("?!") ||
+              prefix.start_with?("?#") || prefix.start_with?("?<=") || prefix.start_with?("?<!")
+            i += 1
+          else
+            count += 1
+            i += 1
+          end
+        else
+          i += 1
+        end
+      end
+      count
+    end
+
+    def compile_backend(pattern, original, backend, opts)
+      return compile_stdlib(pattern, original) if backend == :stdlib
+      Native._native_new(pattern, **opts)
+    rescue ArgumentError => e
+      raise if backend == :fast
+      compile_stdlib(pattern, original, fallback_from: e)
+    end
+
+    def compile_stdlib(pattern, original, fallback_from: nil)
+      return original if original.is_a?(::Regexp)
+      ::Regexp.new(pattern)
+    rescue ::RegexpError => e
+      # Pattern is malformed in both engines (auto path) — surface the
+      # original rust/regex error since it's typically more detailed.
+      # Otherwise propagate the stdlib error as-is.
+      raise(fallback_from ? ArgumentError.new(fallback_from.message) : e)
+    end
+
+    # Maps positional capture indices to names for the stdlib backend so we
+    # can translate `$N` to `\k<name>` (Ruby's gsub ignores `\N` for named
+    # groups). Only invoked from the stdlib path.
+    def stdlib_name_by_index
+      @stdlib_name_by_index ||= @backend.named_captures.flat_map { |n, idxs| idxs.map { |i| [i, n] } }.to_h
+    end
+
+    # Translate rust/regex replacement syntax ($N, ${name}, $$) into Ruby
+    # syntax (\N, \k<name>, $) for the stdlib fallback path.
+    def stdlib_replacement(template, literal)
+      return template.gsub('\\', '\\\\\\\\') if literal
+
+      template.gsub(/\$(\$|\d+|\{[^}]+\})/) do
+        token = ::Regexp.last_match(1)
+        case token
+        when "$" then "$"
+        when /\A\d+\z/
+          name = stdlib_name_by_index[token.to_i]
+          name ? "\\k<#{name}>" : "\\#{token}"
+        else "\\k<#{token[1..-2]}>"
+        end
+      end
+    end
+
+    # Fast path: rust/regex has no native iterate-with-replace, so we scan all
+    # match positions up-front, then splice the result by byte offset in one
+    # pass. Stays UTF-8 since haystack and match slices are.
+    def fast_gsub_with_block(haystack)
       matches = scan_matches(haystack)
       return haystack.dup if matches.empty?
 
@@ -114,31 +254,64 @@ module Fast
       out
     end
 
+    # Stdlib path: String#gsub already does single-pass iterate-and-replace
+    # and sets $~ inside the block, so wrap the current ::MatchData and yield.
+    def stdlib_gsub_with_block(haystack)
+      haystack.gsub(@backend) { yield(MatchData.new(::Regexp.last_match, haystack)).to_s }
+    end
+
     def coerce_string(value)
       return value if value.is_a?(String)
       return value.to_str if value.respond_to?(:to_str)
       raise TypeError, "no implicit conversion of #{value.class} into String"
     end
 
+    # Wraps either a Fast::Regexp::Native::MatchData or a stdlib ::MatchData
+    # so callers see one type regardless of which backend ran.
     class MatchData
       include Enumerable
 
-      def each(&block)
-        to_a.each(&block)
-      end
+      attr_reader :backend, :string
 
-      def values_at(*indices)
-        indices.map { |i| self[i] }
+      def initialize(backend, haystack)
+        @backend = backend
+        @string = haystack
       end
 
+      def native? = @backend.is_a?(Fast::Regexp::Native::MatchData)
+      def stdlib? = !native?
+
+      def native = native? ? @backend : nil
+      def stdlib = stdlib? ? @backend : nil
+
+      def [](key) = @backend[key]
+      def to_a = @backend.to_a
+      def captures = @backend.captures
+      def named_captures = @backend.named_captures
+      def names = @backend.names
+      def size = @backend.size
+      alias_method :length, :size
+      def pre_match = @backend.pre_match
+      def post_match = @backend.post_match
+      def to_s = @backend.to_s
+
+      # Byte-based offsets. Both backends expose these (stdlib MatchData has
+      # `byteoffset` / `byte_begin` / `byte_end` since Ruby 3.2).
+      def byteoffset(key) = @backend.byteoffset(key)
+      def byte_begin(key) = @backend.byte_begin(key)
+      def byte_end(key) = @backend.byte_end(key)
+
+      def each(&block) = to_a.each(&block)
+      def values_at(*indices) = indices.map { |i| self[i] }
+
       def ==(other)
         other.is_a?(MatchData) && to_a == other.to_a && string == other.string
       end
       alias_method :eql?, :==
 
-      def hash
-        [to_a, string].hash
-      end
+      def hash = [to_a, string].hash
+
+      def inspect = "#<Fast::Regexp::MatchData #{to_s.inspect}>"
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast_regexp
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Eric Jacobs