fast_regexp 0.6.1-aarch64-linux → 0.7.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9e8f43c5d2a9aa1903943558c35ab6a46b15df0b752c652f6442bd6a328bce7c
-  data.tar.gz: 666effbf46f4db06dbc5b644c88202daac203e7c167cf060cbb5d1f2e63d66a5
+  metadata.gz: fb638b676baa678009503cd7a42a5a03befb73c00b79a72938480c74cd5a0538
+  data.tar.gz: 0033a9a765b873df3b9984fa138ebc534e9b3f0458d1a8018f71d3f5f768786e
 SHA512:
-  metadata.gz: 38ca3692c0b727e5003acca7e24031b73c19fd2957bfbe715dae5c5edd2065fa93ba9e665d2f6cebbc721513957c25193c5c5ca3125e6be59bbc236244fefe52
-  data.tar.gz: '040688216ab69d2ab613548b3dab2b798e90a776c2cff4d107ddc9f4208943b0439cb8d8124128dcb6015b81a316eae4cf8f8cc49d44bdcf5a7126c6b6216146'
+  metadata.gz: 4d30c68136e478c8adcf061bd06d2df042e1af051bce51fc38076f960c8bb9d6eec0336c895dec3dec369401f1bb9207975a128298cd1ac03e2752f0a3281cb8
+  data.tar.gz: aad4a7176414ee857ed229bc0c4cafcfeba8e2ed93b6743c05e924c5d3c8559541cbc1849553831d475c35946ec5d4dc6f13b389f6b8f308fe88111e64e81d71

data/README.md

@@ -244,7 +244,18 @@ In-depth docs live under [`docs/`](docs/README.md), organized via the
 - **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)
+- **Explainers:** [Engine fallback](docs/explainers/engine-fallback.md), [Benchmarks](docs/explainers/benchmarks.md)
+
+## Performance
+
+Matching runs 8–10x stdlib `::Regexp` on a hit or a miss, scanning 2–5x,
+`gsub` with a template 7–13x; reading a `MatchData` costs the same objects
+as `::MatchData`, and `match?`, `=~`, `===` and `Set#match?` allocate
+nothing. Compiling a pattern is the one place rust/regex is slower (it
+builds its automaton up front), so compile once and keep the object. Every
+operation, with the stdlib equivalent beside it, is on the
+[benchmarks page](docs/explainers/benchmarks.md); reproduce with
+`bundle exec ruby benchmark/operations.rb`.
 
 ## Development
 
@@ -253,6 +264,7 @@ bin/setup     # install deps
 bin/console   # interactive prompt to play around
 rake compile  # (re)compile extension
 rake spec     # run tests
+bundle exec ruby benchmark/operations.rb   # the benchmarks page's table
 ```
 
 ## Contributing

data/lib/fast_regexp/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   class Regexp
-    VERSION = "0.6.1"
+    VERSION = "0.7.0"
   end
 end

data/lib/fast_regexp.rb

@@ -21,6 +21,62 @@ module Fast
       candidates = [File.join(base, abi, "fast_regexp"), File.join(base, "fast_regexp")]
       candidates.find { |stem| NATIVE_EXTENSIONS.any? { |ext| File.exist?(stem + ext) } }
     end
+
+    # One match, whichever engine produced it. On the fast path the match
+    # *is* a `Fast::Regexp::Native::MatchData`, a subclass of this one
+    # defined by the extension (so it must exist before the extension
+    # loads); on the stdlib path it's an instance of this class wrapping the
+    # `::MatchData`. Same public surface either way.
+    class MatchData
+      include Enumerable
+
+      attr_reader :backend
+
+      def initialize(backend)
+        @backend = backend
+      end
+
+      def native? = false
+      def stdlib? = true
+
+      def native = nil
+      def stdlib = @backend
+
+      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
+      alias_method :match, :to_s
+
+      # The haystack the match was taken over: `::MatchData#string` is already
+      # a frozen snapshot, the same thing the native subclass keeps.
+      def string = @backend.string
+
+      # Byte-based offsets. `::MatchData#byteoffset` exists since Ruby 3.2;
+      # its `byte_begin`/`byte_end` don't (3.4 added `bytebegin`/`byteend`),
+      # so those two derive from `byteoffset` here.
+      def byteoffset(key) = @backend.byteoffset(key)
+      def byte_begin(key) = byteoffset(key)[0]
+      def byte_end(key) = byteoffset(key)[1]
+
+      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
+
+      def inspect = "#<Fast::Regexp::MatchData #{to_s.inspect}>"
+    end
   end
 end
 
@@ -30,6 +86,22 @@ require native
 
 module Fast
   class Regexp
+    class Native
+      class MatchData
+        def native? = true
+        def stdlib? = false
+
+        def native = self
+        def stdlib = nil
+        def backend = self
+
+        # Immutable, so a copy is the object itself (the wrapped class has no
+        # allocator for `dup`/`clone` to go through).
+        def dup = self
+        def clone(freeze: nil) = self
+      end
+    end
+
     RUBY_FLAG_MAP = {
       ::Regexp::IGNORECASE => "i",
       ::Regexp::EXTENDED => "x",
@@ -45,13 +117,21 @@ module Fast
         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:
+      # Bulk-compile a set of patterns. Two call shapes:
+      #
+      #   Fast::Regexp.create_many(word: '\w+', num: '\d+')
+      #   # => { word: #<Fast::Regexp ...>, num: #<Fast::Regexp ...> }
       #
-      #   RE = Fast::Regexp.create_many(word: '\w+', num: '\d+').freeze
-      #   RE[:word].match("hello")
-      def create_many(**patterns)
-        patterns.transform_values { |pat| new(pat) }
+      #   Fast::Regexp.create_many('\w+', '\d+')
+      #   # => [#<Fast::Regexp ...>, #<Fast::Regexp ...>]
+      #
+      # Mixing the two raises ArgumentError — pick one shape per call.
+      def create_many(*patterns, **named)
+        if !patterns.empty? && !named.empty?
+          raise ArgumentError, "create_many accepts positional patterns OR keyword patterns, not both"
+        end
+        return named.transform_values { |pat| new(pat) } if patterns.empty?
+        patterns.map { |pat| new(pat) }
       end
 
       private
@@ -88,8 +168,9 @@ module Fast
 
     def match(haystack)
       haystack = coerce_string(haystack)
-      raw = fast? ? @backend._native_match(haystack) : @backend.match(haystack)
-      raw && MatchData.new(raw, haystack)
+      return @backend._native_match(haystack) if fast?
+      m = @backend.match(haystack)
+      m && MatchData.new(m)
     end
 
     def match?(haystack)
@@ -105,8 +186,10 @@ module Fast
     # 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)
+      haystack = other.to_str
+      return @backend._native_find(haystack) if fast?
+      m = @backend.match(haystack)
+      m && m.byteoffset(0)[0]
     end
 
     def scan(haystack)
@@ -115,22 +198,17 @@ module Fast
 
     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
+      return @backend.scan_matches(haystack) if fast?
+      results = []
+      haystack.scan(@backend) { results << MatchData.new(::Regexp.last_match) }
+      results
     end
 
     def sub(haystack, replacement = nil, literal: false, &block)
       haystack = coerce_string(haystack)
-      if block
+      if block_given?
         raise ArgumentError, "wrong number of arguments (given 2, expected 1 with block)" if replacement
-        m = match(haystack)
-        return haystack.dup unless m
-        "#{m.pre_match}#{block.call(m)}#{m.post_match}"
+        fast? ? @backend._native_sub_block(haystack, &block) : stdlib_sub_with_block(haystack, &block)
       else
         raise ArgumentError, "wrong number of arguments (given 1, expected 2)" if replacement.nil?
         replacement = coerce_string(replacement)
@@ -144,9 +222,9 @@ module Fast
 
     def gsub(haystack, replacement = nil, literal: false, &block)
       haystack = coerce_string(haystack)
-      if block
+      if block_given?
         raise ArgumentError, "wrong number of arguments (given 2, expected 1 with block)" if replacement
-        fast? ? fast_gsub_with_block(haystack, &block) : stdlib_gsub_with_block(haystack, &block)
+        fast? ? @backend._native_gsub_block(haystack, &block) : stdlib_gsub_with_block(haystack, &block)
       else
         raise ArgumentError, "wrong number of arguments (given 1, expected 2)" if replacement.nil?
         replacement = coerce_string(replacement)
@@ -246,29 +324,14 @@ module Fast
       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?
-
-      out = String.new(encoding: Encoding::UTF_8)
-      cursor = 0
-      matches.each do |m|
-        bs, be = m.byteoffset(0)
-        out << haystack.byteslice(cursor, bs - cursor) if bs > cursor
-        out << yield(m).to_s
-        cursor = be
-      end
-      out << haystack.byteslice(cursor, haystack.bytesize - cursor) if cursor < haystack.bytesize
-      out
+    # Stdlib path: String#sub/#gsub already do single-pass iterate-and-replace
+    # and set $~ inside the block, so wrap the current ::MatchData and yield.
+    def stdlib_sub_with_block(haystack)
+      haystack.sub(@backend) { yield(MatchData.new(::Regexp.last_match)).to_s }
     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 }
+      haystack.gsub(@backend) { yield(MatchData.new(::Regexp.last_match)).to_s }
     end
 
     def coerce_string(value)
@@ -276,53 +339,5 @@ module Fast
       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
-
-      attr_reader :backend, :string
-
-      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
-
-      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.6.1
+  version: 0.7.0
 platform: aarch64-linux
 authors:
 - Eric Jacobs
@@ -9,10 +9,10 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-05-16 00:00:00.000000000 Z
+date: 2026-09-19 00:00:00.000000000 Z
 dependencies: []
 description: 'Ruby bindings to rust/regex with a Fast::Regexp API: MatchData, sub/gsub,
-  ===, =~, named captures, and GVL release for thread/fiber-friendly matching.'
+  ===, =~, & named captures.'
 email:
 - eric@ebj.dev
 executables: []
@@ -31,6 +31,7 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/jetpks/fast_regexp/issues
+  changelog_uri: https://github.com/jetpks/fast_regexp/blob/main/CHANGELOG.md
   homepage_uri: https://github.com/jetpks/fast_regexp
   source_code_uri: https://github.com/jetpks/fast_regexp
 post_install_message: