corvus_regex_ecma262 0.1.1-x86_64-linux-gnu

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5b367e7b382030f1053ab030ff79bbf0a5d28d46e6192a87f6c6cce67b600fc9
+  data.tar.gz: b833e7969f5d9741f94756cbc6d6418dd2dac9be14d4f558d7315db590472fab
+SHA512:
+  metadata.gz: 9c52447221dc4c558802a860ec178ff3e172d5cf43e6fcf64ba9b6ea6eff21d89ee3ad4e11c10f0b298ffac6c60d5588edf86a66b15016f8dae5c90a423cb735
+  data.tar.gz: 21290d0e7c5465e85dd40f759eb9c56bfc1da00527261d5627d08c4c99ee5e0ff12ef12f5b446cd12bd903e89520c2602f9acdefbf0d9dbcdf85cd103ae32534

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,100 @@
+# corvus-regex-ecma262 for Ruby
+
+Regular expressions with the grammar and the answers of ECMA-262, the `RegExp` of JavaScript, for Ruby: the
+[corvus-regex-ecma262](https://github.com/corvus-dotnet/corvus-regex-ecma262-rs) Rust crate, as a gem with native
+builds for Linux (glibc and musl), macOS and Windows, x64 and arm64, for Ruby 3.3 and later.
+
+- Every flag: `d`, `g`, `i`, `m`, `s`, `u`, `v` and `y`, with the grammar of each. Without `u` or `v` a pattern is
+  read by the Annex B grammar and matched by UTF-16 code unit, as ECMA-262 matches it; with them, by code point. The
+  `v` flag has nested classes, the difference and the intersection of classes, strings in a class and the properties
+  of strings.
+- ECMAScript 2025: lookbehind, named groups (and a name shared between alternatives), modifier groups such as
+  `(?i:...)`, and every Unicode property ECMA-262 lists, from Unicode 17 tables the crate carries.
+- UTF-8 strings (and US-ASCII, and binary strings holding UTF-8) and UTF-16LE strings, each matched as it is held.
+  A pattern answers as it does in a browser or Node, which Ruby's `Regexp` does not: `^` and `$`, `.`, `\d`, `\w`,
+  `\b`, case folding, `\p{...}` and the rest read as JavaScript reads them.
+- A pattern without a backreference is matched in time proportional to its size times the text, and `match` and
+  `match?` take a timeout, so neither a pattern nor a text from outside can make a program hang.
+
+**Compliance.** Over the [ECMA-262 test data](https://github.com/corvus-dotnet/ecma262-regex-test-data) (what V8 says
+about 109,547 patterns and 5,325,026 texts, `exec`, the global search, `replace` and `split` among them), through this
+gem over UTF-16LE and UTF-8 strings, it gives 23,647,077 right answers and none wrong, refuses no valid pattern,
+accepts no invalid one and reaches no limit. CI runs the whole data through each native gem on its platform.
+
+## Install
+
+```
+gem install corvus_regex_ecma262
+```
+
+## Getting started
+
+```ruby
+require "corvus_regex_ecma262"
+
+# The flags are those of new RegExp(pattern, flags).
+date = CorvusRegexEcma262::Regex.new('(?<year>\d{4})-(?<month>\d{2})', "gu")
+
+date.match?("due 2026-10")                          # => true
+m = date.match("due 2026-10")
+m[:year]                                            # => "2026"
+m.offset                                            # => [4, 11]
+
+# Every match of a global search, as matchAll makes it.
+date.each_match("2026-10, 2027-01").map(&:to_s)     # => ["2026-10", "2027-01"]
+
+# replace replaces every match with the g flag, and the first without it; a block may give each replacement.
+date.replace("2026-10, 2027-01", "$<month>/$1")     # => "10/2026, 01/2027"
+date.replace("2026-10") { |m| m[:month] }           # => "10"
+
+# split splices in what the groups captured; a group that did not take part is nil.
+CorvusRegexEcma262.compile('\s*(;)\s*').split("a ; b;c")  # => ["a", ";", "b", ";", "c"]
+```
+
+## The API
+
+| | |
+|---|---|
+| `Regex.new(pattern, flags = "")`, `CorvusRegexEcma262.compile` | Compiles a pattern as `new RegExp(pattern, flags)` does. |
+| `Regex.valid?(pattern, flags = "")` | Whether a pattern is valid, without compiling it. |
+| `match?(string, pos = 0, timeout: nil)` | `RegExp.prototype.test` with `lastIndex` at `pos` (at `pos` alone with `y`). |
+| `match(string, pos = 0, timeout: nil)` | The first match at or after `pos`, as `exec` finds it: a `Match`, or `nil`; with a block, the block's result. |
+| `each_match(string)` | A global search as `matchAll` makes it: yields each `Match`, or returns an `Enumerator`. |
+| `match_count(string)` | The number of matches of a global search, without making them. |
+| `replace(string, replacement)`, `replace(string) { \|m\| ... }` | `String.prototype.replace`: the first match, or every match with `g`. |
+| `replace_all(string, replacement)` | `String.prototype.replaceAll`: every match. |
+| `split(string, limit = nil)` | `String.prototype.split`: an Array of Strings, `nil` for a group that did not take part. |
+| `source`, `flags`, `group_count`, `names` | What the pattern is. |
+
+A `Match` is read as a `MatchData` is: `m[g]` (a number, a name or a Symbol), `captures`, `named_captures`, `to_a`,
+`values_at`, `pre_match`, `post_match`, `begin(g)`, `end(g)` and `offset(g)` (nil for a group that did not take part),
+`byte_begin`, `byte_end` and `byteoffset`, `string` and `regexp`.
+
+**Positions.** Over a UTF-8 string, `begin`, `end` and `offset` are in characters, as Ruby counts them, and the
+`byte_` forms in bytes; over a UTF-16LE string they are in UTF-16 code units, as JavaScript counts them. Without `u` or
+`v` a pattern is matched by UTF-16 code unit, so a match can take half of a character beyond the Basic Multilingual
+Plane: over UTF-8 its text holds that half as U+FFFD and its character positions are the whole character's (its byte
+positions are the character's start and third byte); over UTF-16LE it is the lone half, as in JavaScript.
+
+**Errors.** `InvalidPatternError`, `InvalidFlagsError`, `PatternTooLargeError` and `MatchLimitError` (a match that
+reached its timeout or its cap on backtracking memory) are each a `CorvusRegexEcma262::Error`, a `StandardError`. A
+string that is not valid in its encoding raises `ArgumentError`; one in another encoding, `EncodingError`.
+
+**Threads.** A `Regex` is frozen and may be used from any number of threads. A string cannot change while a global
+search walks it.
+
+## Benchmarks
+
+The Industry workloads of dotnet/performance, this gem against Ruby's `Regexp` and V8, are on the central page,
+[corvus-oss.org/corvus-regex-ecma262-benchmarks](https://corvus-oss.org/corvus-regex-ecma262-benchmarks/), measured
+nightly on one runner with every other Corvus ECMA-262 engine.
+
+## Repository
+
+- `ext/corvus_regex_ecma262`: the native extension (magnus, over the crate); `lib/`: the Ruby API.
+- `test/`: the tests; `tools/dataset.rb`: the test-data runner (`ruby -Ilib tools/dataset.rb <data> wrong.tsv`).
+- `tools/bench`: the benchmark harness and the script the image runs; `Dockerfile`: the image the central page runs.
+
+## Licence
+
+Apache-2.0. See [LICENSE](LICENSE).

data/lib/corvus_regex_ecma262/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CorvusRegexEcma262
+  VERSION = "0.1.1"
+end

data/lib/corvus_regex_ecma262.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+# ECMA-262 (JavaScript) regular expressions for Ruby, with the grammar and the answers of RegExp, every flag, backed by
+# the corvus-regex-ecma262 Rust crate.
+#
+#   date = CorvusRegexEcma262::Regex.new('(?<year>\d{4})-(?<month>\d{2})', "gu")
+#   date.match?("due 2026-10")                       # => true
+#   date.match("due 2026-10")[:year]                 # => "2026"
+#   date.each_match("2026-10, 2027-01").map(&:to_s)  # => ["2026-10", "2027-01"]
+#   date.replace("2026-10, 2027-01", "$<month>/$1")  # => "10/2026, 01/2027"
+#
+# A String is matched as it is held: UTF-8 (or US-ASCII, or binary holding UTF-8) as UTF-8, with positions in
+# characters as Ruby counts them and byte positions beside them; UTF-16LE as UTF-16, with positions in code units.
+# Without the u or v flag a pattern is matched by UTF-16 code unit, so a match can take half of a character beyond the
+# Basic Multilingual Plane: over UTF-8 its text holds that half as U+FFFD, and its start and end in characters are the
+# whole character's.
+require_relative "corvus_regex_ecma262/version"
+
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require_relative "corvus_regex_ecma262/#{Regexp.last_match(1)}/corvus_regex_ecma262"
+rescue LoadError
+  require_relative "corvus_regex_ecma262/corvus_regex_ecma262"
+end
+
+module CorvusRegexEcma262
+  UTF16LE = Encoding::UTF_16LE
+
+  # A compiled ECMA-262 regular expression, as new RegExp(pattern, flags) compiles it. It is immutable, and may be
+  # used from any number of threads.
+  class Regex
+    attr_reader :names
+
+    # Compiles a pattern with the flags new RegExp(pattern, flags) takes, any of dgimsuvy. Raises InvalidPatternError,
+    # InvalidFlagsError or PatternTooLargeError (each an Error).
+    def initialize(pattern, flags = "")
+      @native = Native::Regex.new(CorvusRegexEcma262.utf8(pattern), flags.to_s)
+      @names = @native.names.freeze
+      freeze
+    end
+
+    # Whether a pattern is valid with the flags, without compiling it.
+    def self.valid?(pattern, flags = "")
+      Native::Regex.valid?(CorvusRegexEcma262.utf8(pattern), flags.to_s)
+    end
+
+    # The pattern as it was given, as UTF-8.
+    def source = @native.source
+
+    # The flags as RegExp.prototype.flags writes them, in the order dgimsuvy.
+    def flags = @native.flags
+
+    # The number of capturing groups.
+    def group_count = @native.group_count
+
+    # Whether the pattern matches at or after pos (at pos alone with the y flag), as RegExp.prototype.test with
+    # lastIndex set to pos. With timeout: (seconds), a match that reaches it raises MatchLimitError.
+    def match?(string, pos = 0, timeout: nil)
+      @native.test(string, CorvusRegexEcma262.unit_of(string, pos), timeout&.to_f)
+    end
+
+    # The first match at or after pos, as exec finds it with lastIndex set to pos: a Match, or nil. With a block, the
+    # block's result for the match, or nil. With timeout: (seconds), a match that reaches it raises MatchLimitError.
+    def match(string, pos = 0, timeout: nil)
+      groups = @native.exec(string, CorvusRegexEcma262.unit_of(string, pos), timeout&.to_f)
+      return nil unless groups
+
+      m = Match.new(self, string, groups, Positions.new(string))
+      block_given? ? yield(m) : m
+    end
+
+    # Every match of a global search of the string, as matchAll makes one: yields each Match, or returns an
+    # Enumerator. After an empty match the search goes on one character later, and with the y flag each match must
+    # start where the one before ended.
+    def each_match(string)
+      return enum_for(:each_match, string) unless block_given?
+
+      string = CorvusRegexEcma262.snapshot(string)
+      positions = Positions.new(string)
+      @native.each(string) { |groups| yield Match.new(self, string, groups, positions) }
+      self
+    end
+
+    # The number of matches of a global search, without making them.
+    def match_count(string) = @native.count(string)
+
+    # The string with the first match replaced, or every match with the g flag, as String.prototype.replace replaces
+    # them. The replacement is a template ($& the match, $` the text before it, $' the text after it, $1 to $99 a
+    # group, $<name> a named group, $$ a dollar sign), or the block's result for each Match.
+    def replace(string, replacement = nil, &block)
+      substitute(string, replacement, @native.global?, &block)
+    end
+
+    # The string with every match replaced, whether or not the g flag is set (String.prototype.replaceAll).
+    def replace_all(string, replacement = nil, &block)
+      substitute(string, replacement, true, &block)
+    end
+
+    # The string split around the matches, as String.prototype.split(separator, limit) splits it: what each group
+    # captured is spliced in after the piece before it (nil for a group that did not take part), an empty match at
+    # the start or the end splits nothing, and there are at most limit pieces.
+    def split(string, limit = nil)
+      @native.split(string, limit).map { |piece| piece&.force_encoding(CorvusRegexEcma262.result_encoding(string)) }
+    end
+
+    def inspect = "#<CorvusRegexEcma262::Regex /#{source}/#{flags}>"
+    alias to_s inspect
+
+    def ==(other) = other.is_a?(Regex) && other.source == source && other.flags == flags
+    alias eql? ==
+    def hash = [source, flags].hash
+
+    private
+
+    def substitute(string, replacement, all)
+      unless block_given?
+        raise ArgumentError, "a replacement or a block" if replacement.nil?
+
+        template = string.encoding == UTF16LE ? replacement.encode(UTF16LE) : CorvusRegexEcma262.utf8(replacement)
+        return @native.replace(string, template, all).force_encoding(CorvusRegexEcma262.result_encoding(string))
+      end
+      raise ArgumentError, "a replacement or a block, not both" unless replacement.nil?
+
+      string = CorvusRegexEcma262.snapshot(string)
+      out = +""
+      out.force_encoding(CorvusRegexEcma262.result_encoding(string))
+      last = 0
+      unit = string.encoding == UTF16LE ? 2 : 1
+      positions = Positions.new(string)
+      @native.each(string) do |groups|
+        m = Match.new(self, string, groups, positions)
+        out << string.byteslice(last * unit, (groups[0] - last) * unit) << yield(m).to_s
+        last = groups[1]
+        break unless all
+      end
+      out << string.byteslice(last * unit, string.bytesize - last * unit)
+    end
+  end
+
+  # Where a match and its groups are, read as a MatchData is: by number, by name (String or Symbol), with begin, end
+  # and offset in characters (in code units for a UTF-16LE string), and byte_begin, byte_end and byteoffset in bytes.
+  class Match
+    attr_reader :string, :regexp
+
+    def initialize(regexp, string, groups, positions)
+      @regexp = regexp
+      @string = string
+      @groups = groups
+      @positions = positions
+    end
+
+    # The number of groups, the whole match among them.
+    def size = @regexp.group_count + 1
+    alias length size
+
+    def names = @regexp.names
+
+    # The text of a group, by number, name or Symbol: nil when it did not take part.
+    def [](group)
+      s, e = span(group)
+      return nil if s.negative?
+
+      text(s, e)
+    end
+
+    # The start of the group in characters (code units for UTF-16LE), or nil when it did not take part.
+    def begin(group = 0)
+      s, = span(group)
+      s.negative? ? nil : @positions.char(s, false)
+    end
+
+    # The end of the group in characters (code units for UTF-16LE), or nil when it did not take part.
+    def end(group = 0)
+      _, e = span(group)
+      e.negative? ? nil : @positions.char(e, true)
+    end
+
+    # [begin, end] of the group, or [nil, nil] when it did not take part.
+    def offset(group = 0) = [self.begin(group), self.end(group)]
+
+    def byte_begin(group = 0)
+      s, = span(group)
+      s.negative? ? nil : s * unit
+    end
+
+    def byte_end(group = 0)
+      _, e = span(group)
+      e.negative? ? nil : e * unit
+    end
+
+    def byteoffset(group = 0) = [byte_begin(group), byte_end(group)]
+
+    # The text of every capturing group, nil for one that did not take part.
+    def captures = (1...size).map { |g| self[g] }
+
+    # The text of each name's group.
+    def named_captures = names.to_h { |n| [n, self[n]] }
+
+    def to_a = (0...size).map { |g| self[g] }
+    def values_at(*groups) = groups.map { |g| self[g] }
+    def to_s = self[0]
+    def pre_match = text(0, @groups[0])
+    def post_match = @string.byteslice(@groups[1] * unit, @string.bytesize - (@groups[1] * unit))
+
+    def inspect = "#<CorvusRegexEcma262::Match #{to_s.inspect} #{offset.inspect}>"
+
+    private
+
+    def unit = @string.encoding == UTF16LE ? 2 : 1
+
+    # [start, end] of a group in engine positions (-1 for one that did not take part).
+    def span(group)
+      i = case group
+          when Integer
+            raise IndexError, "index #{group} out of matches" if group.negative? || group >= size
+
+            group
+          when String, Symbol
+            k = names.index(group.to_s)
+            raise IndexError, "undefined group name reference: #{group}" unless k
+
+            size + k
+          else
+            raise TypeError, "a group is an Integer, a String or a Symbol"
+          end
+      [@groups[2 * i], @groups[(2 * i) + 1]]
+    end
+
+    def text(s, e)
+      piece = @string.byteslice(s * unit, (e - s) * unit)
+      # A half of a character (without u or v, over UTF-8) is no UTF-8: written as U+FFFD, as the crate writes it.
+      piece.valid_encoding? ? piece : piece.scrub("�")
+    end
+  end
+
+  # Byte positions to character positions, going on from where it was last asked, since a search asks in order.
+  class Positions
+    def initialize(string)
+      @string = string
+      @identity = string.encoding == UTF16LE || string.ascii_only?
+      @byte = 0
+      @char = 0
+    end
+
+    # The character index of a byte position; a position inside a character (between the halves of one beyond the
+    # Basic Multilingual Plane) is its start, or (for an end) past it.
+    def char(byte, at_end)
+      return byte if @identity
+
+      @byte = @char = 0 if byte < @byte
+      inside = byte < @string.bytesize && (@string.getbyte(byte) & 0xC0) == 0x80
+      target = byte
+      target -= 1 while inside && target.positive? && (@string.getbyte(target) & 0xC0) == 0x80
+      @char += @string.byteslice(@byte, target - @byte).length
+      @byte = target
+      inside && at_end ? @char + 1 : @char
+    end
+  end
+
+  class << self
+    # Compiles a pattern: Regex.new(pattern, flags).
+    def compile(pattern, flags = "") = Regex.new(pattern, flags)
+
+    # Whether a pattern is valid with the flags, without compiling it.
+    def valid?(pattern, flags = "") = Regex.valid?(pattern, flags)
+
+    # The version of the crate the extension was built with.
+    def crate_version = Native.crate_version
+
+    # @api private
+    def utf8(s)
+      s = s.to_s
+      return s if s.encoding == Encoding::UTF_8 || (s.encoding == Encoding::US_ASCII && s.ascii_only?)
+
+      # A lone surrogate (in a UTF-16 pattern) is read as U+FFFD, as the crate's UTF-8 patterns have none.
+      s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "�")
+    end
+
+    # @api private: the string as a search that runs a block walks it, frozen, so that it cannot change under the
+    # search and any number of searches may walk it at once. A string that is not frozen is copied as Ruby copies a
+    # String, sharing its bytes until either is changed.
+    def snapshot(string) = string.frozen? ? string : string.dup.freeze
+
+    # @api private
+    def result_encoding(string) = string.encoding == UTF16LE ? UTF16LE : Encoding::UTF_8
+
+    # @api private: the engine position of a character position.
+    def unit_of(string, pos)
+      raise ArgumentError, "pos must not be negative" if pos.negative?
+      return pos if string.encoding == UTF16LE || string.ascii_only? || pos.zero?
+      # Past the end, as lastIndex past a string's length: no match.
+      return string.bytesize + 1 if pos > string.length
+
+      string[0, pos].bytesize
+    end
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: corvus_regex_ecma262
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: x86_64-linux-gnu
+authors:
+- endjin
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-21 00:00:00.000000000 Z
+dependencies: []
+description: Regular expressions that answer as JavaScript's RegExp does, every flag
+  (dgimsuvy), over UTF-8 and UTF-16LE strings, with the corvus-regex-ecma262 Rust
+  crate.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/corvus_regex_ecma262.rb
+- lib/corvus_regex_ecma262/3.3/corvus_regex_ecma262.so
+- lib/corvus_regex_ecma262/3.4/corvus_regex_ecma262.so
+- lib/corvus_regex_ecma262/4.0/corvus_regex_ecma262.so
+- lib/corvus_regex_ecma262/version.rb
+homepage: https://github.com/corvus-dotnet/corvus-regex-ecma262-ruby
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/corvus-dotnet/corvus-regex-ecma262-ruby
+  bug_tracker_uri: https://github.com/corvus-dotnet/corvus-regex-ecma262-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.22
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: 'ECMA-262 (JavaScript) regular expressions for Ruby: the grammar and the
+  answers of RegExp, backed by Rust.'
+test_files: []