re2 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8588a481a52f07a6c965094bb69c1aee177add80d071aee3a1771f97e19dc4f6
-  data.tar.gz: bb123e3a2d5352379548bf68f57fd195c8aa458e2da06f0864b7135682c19b1d
+  metadata.gz: ddba6fe8bb8c7e51bcb0b8f4346b39ca903978ff6697a4c14d06702baae10598
+  data.tar.gz: f8905eeeeff7e4bebc532d23fa19b29f1c3e2a88ea303a5aa879bafb4af4e1ed
 SHA512:
-  metadata.gz: b421f15ace868de905dece66db9e607636624cf2548eabe6be9979c397ac825035c0b24a5d8e8d6a351aa5809f6265d07f7b67a4c720a81e0b4e78f8d4599c67
-  data.tar.gz: fb7314faaf44a8847eadf207b0226ea71071ddb02ae41b7644ade69b69c06ff86f7c5d1a34042b4ef90633b98b6185bc07a6e2241bfa570089525e73eca6a61a
+  metadata.gz: 44184ad41a55746903fcd350fbf473d26266c710e324eaac879b46ff45e3b77120d5100a25f5188e2d938cafbc48caf909506d79cf07c31522ccfb9e789c2ce0
+  data.tar.gz: eb282abd472e00ebcbb10e38f84c62bbac785bd139c69140647a29a157475600b6845472edb41ed42234caf5729188052cc1459b1ac2775c544ed0e905c6039d

data/README.md

@@ -4,9 +4,9 @@ re2 [![Build Status](https://github.com/mudge/re2/actions/workflows/tests.yml/ba
 A Ruby binding to [re2][], an "efficient, principled regular expression
 library".
 
-**Current version:** 1.5.0  
-**Supported Ruby versions:** 1.8.7, 1.9.3, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 3.0  
-**Supported re2 versions:** libre2.0 (< 2020-03-02), libre2.1 (2020-03-02), libre2.6 (2020-03-03), libre2.7 (2020-05-01), libre2.8 (2020-07-06), libre2.9 (2020-11-01)
+**Current version:** 1.7.0  
+**Supported Ruby versions:** 1.8.7, 1.9.3, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 3.0, 3.1, 3.2  
+**Supported re2 versions:** libre2.0 (< 2020-03-02), libre2.1 (2020-03-02), libre2.6 (2020-03-03), libre2.7 (2020-05-01), libre2.8 (2020-07-06), libre2.9 (2020-11-01), libre2.10 (2022-12-01), libre2.11 (2023-07-01)
 
 Installation
 ------------
@@ -22,7 +22,7 @@ If you are using Debian, you can install the [libre2-dev][] package like so:
 
     $ sudo apt-get install libre2-dev
 
-Recent versions of re2 require a compiler with C++11 support such as [clang](http://clang.llvm.org/) 3.4 or [gcc](https://gcc.gnu.org/) 4.8.
+Recent versions of re2 require a compiler with C++14 support such as [clang](http://clang.llvm.org/) 3.4 or [gcc](https://gcc.gnu.org/) 5.
 
 If you are using a packaged Ruby distribution, make sure you also have the
 Ruby header files installed such as those provided by the [ruby-dev][] package
@@ -137,7 +137,7 @@ the pattern. After all patterns have been added, the set can be compiled using
 `RE2::Set#compile`, and then `RE2::Set#match` will return an `Array<Integer>`
 containing the indices of all the patterns that matched.
 
-``` ruby
+```ruby
 set = RE2::Set.new
 set.add("abc") #=> 0
 set.add("def") #=> 1
@@ -147,6 +147,27 @@ set.match("abcdefghi") #=> [0, 1, 2]
 set.match("ghidefabc") #=> [2, 1, 0]
 ```
 
+As of 1.6.0, you can use [Ruby's pattern matching](https://docs.ruby-lang.org/en/3.0/syntax/pattern_matching_rdoc.html) against `RE2::MatchData` with both array patterns and hash patterns:
+
+```ruby
+case RE2('(\w+) (\d+)').match("Alice 42")
+in [name, age]
+  puts "My name is #{name} and I am #{age} years old"
+else
+  puts "No match!"
+end
+# My name is Alice and I am 42 years old
+
+
+case RE2('(?P<name>\w+) (?P<age>\d+)').match("Alice 42")
+in {name:, age:}
+  puts "My name is #{name} and I am #{age} years old"
+else
+  puts "No match!"
+end
+# My name is Alice and I am 42 years old
+```
+
 Features
 --------
 
@@ -185,13 +206,15 @@ Features
   [`RE2.escape(unquoted)`](https://github.com/google/re2/blob/2016-02-01/re2/re2.h#L418) and
   `RE2.quote(unquoted)`
 
+* Pattern matching with `RE2::MatchData`
+
 Contributions
 -------------
 
 * Thanks to [Jason Woods](https://github.com/driskell) who contributed the
   original implementations of `RE2::MatchData#begin` and `RE2::MatchData#end`;
 * Thanks to [Stefano Rivera](https://github.com/stefanor) who first contributed C++11 support;
-* Thanks to [Stan Hu](https://github.com/stanhu) for reporting a bug with empty patterns and `RE2::Regexp#scan`;
+* Thanks to [Stan Hu](https://github.com/stanhu) for reporting a bug with empty patterns and `RE2::Regexp#scan` and for contributing support for libre2.11 (2023-07-01);
 * Thanks to [Sebastian Reitenbach](https://github.com/buzzdeee) for reporting
   the deprecation and removal of the `utf8` encoding option in re2;
 * Thanks to [Sergio Medina](https://github.com/serch) for reporting a bug when

data/ext/re2/extconf.rb

@@ -44,22 +44,30 @@ unless have_library("re2")
   abort "You must have re2 installed and specified with --with-re2-dir, please see https://github.com/google/re2/wiki/Install"
 end
 
-# Recent versions of re2 now require a compiler with C++11 support
-checking_for("re2 requires C++11 compiler") do
-  minimal_program = <<SRC
+minimal_program = <<SRC
 #include <re2/re2.h>
 int main() { return 0; }
 SRC
 
-  unless try_compile(minimal_program, compile_options)
-    if try_compile(minimal_program, compile_options + " -std=c++11")
-      compile_options << " -std=c++11"
-      $CPPFLAGS << " -std=c++11"
-    elsif try_compile(minimal_program, compile_options + " -std=c++0x")
-      compile_options << " -std=c++0x"
-      $CPPFLAGS << " -std=c++0x"
-    else
-      abort "Cannot compile re2 with your compiler: recent versions require C++11 support."
+re2_requires_version_flag = checking_for("re2 that requires explicit C++ version flag") do
+  !try_compile(minimal_program, compile_options)
+end
+
+if re2_requires_version_flag
+  # Recent versions of re2 depend directly on abseil, which requires a
+  # compiler with C++14 support (see
+  # https://github.com/abseil/abseil-cpp/issues/1127 and
+  # https://github.com/abseil/abseil-cpp/issues/1431). However, the
+  # `std=c++14` flag doesn't appear to suffice; we need at least
+  # `std=c++17`.
+  abort "Cannot compile re2 with your compiler: recent versions require C++14 support." unless %w[c++20 c++17 c++11 c++0x].any? do |std|
+    checking_for("re2 that compiles with #{std} standard") do
+      if try_compile(minimal_program, compile_options + " -std=#{std}")
+        compile_options << " -std=#{std}"
+        $CPPFLAGS << " -std=#{std}"
+
+        true
+      end
     end
   end
 end

data/ext/re2/re2.cc

@@ -393,7 +393,7 @@ re2::StringPiece *re2_matchdata_find_match(VALUE idx, VALUE self) {
 /*
  * Returns the number of elements in the match array (including nils).
  *
- * @return [Fixnum] the number of elements
+ * @return [Integer] the number of elements
  * @example
  *   m = RE2::Regexp.new('(\d+)').match("bob 123")
  *   m.size      #=> 2
@@ -409,8 +409,8 @@ static VALUE re2_matchdata_size(VALUE self) {
 /*
  * Returns the offset of the start of the nth element of the matchdata.
  *
- * @param [Fixnum, String, Symbol] n the name or number of the match
- * @return [Fixnum] the offset of the start of the match
+ * @param [Integer, String, Symbol] n the name or number of the match
+ * @return [Integer] the offset of the start of the match
  * @example
  *   m = RE2::Regexp.new('ob (\d+)').match("bob 123")
  *   m.begin(0)  #=> 1
@@ -439,8 +439,8 @@ static VALUE re2_matchdata_begin(VALUE self, VALUE n) {
 /*
  * Returns the offset of the character following the end of the nth element of the matchdata.
  *
- * @param [Fixnum, String, Symbol] n the name or number of the match
- * @return [Fixnum] the offset of the character following the end of the match
+ * @param [Integer, String, Symbol] n the name or number of the match
+ * @return [Integer] the offset of the character following the end of the match
  * @example
  *   m = RE2::Regexp.new('ob (\d+) b').match("bob 123 bob")
  *   m.end(0)  #=> 9
@@ -584,7 +584,7 @@ static VALUE re2_matchdata_named_match(const char* name, VALUE self) {
  * @overload [](index)
  *   Access a particular match by index.
  *
- *   @param [Fixnum] index the index of the match to fetch
+ *   @param [Integer] index the index of the match to fetch
  *   @return [String, nil] the specified match
  *   @example
  *     m = RE2::Regexp.new('(\d+)').match("bob 123")
@@ -593,8 +593,8 @@ static VALUE re2_matchdata_named_match(const char* name, VALUE self) {
  * @overload [](start, length)
  *   Access a range of matches by starting index and length.
  *
- *   @param [Fixnum] start the index from which to start
- *   @param [Fixnum] length the number of elements to fetch
+ *   @param [Integer] start the index from which to start
+ *   @param [Integer] length the number of elements to fetch
  *   @return [Array<String, nil>] the specified matches
  *   @example
  *     m = RE2::Regexp.new('(\d+)').match("bob 123")
@@ -687,14 +687,117 @@ static VALUE re2_matchdata_inspect(VALUE self) {
   return result;
 }
 
+/*
+ * Returns the array of submatches for pattern matching.
+ *
+ * @return [Array<String, nil>] the array of submatches
+ * @example
+ *   m = RE2::Regexp.new('(\d+)').match("bob 123")
+ *   m.deconstruct    #=> ["123"]
+ *
+ * @example pattern matching
+ *   case RE2::Regexp.new('(\d+) (\d+)').match("bob 123 456")
+ *   in x, y
+ *     puts "Matched #{x} #{y}"
+ *   else
+ *     puts "Unrecognised match"
+ *   end
+ */
+static VALUE re2_matchdata_deconstruct(VALUE self) {
+  int i;
+  re2_matchdata *m;
+  re2_pattern *p;
+  re2::StringPiece *match;
+  VALUE array;
+
+  Data_Get_Struct(self, re2_matchdata, m);
+  Data_Get_Struct(m->regexp, re2_pattern, p);
+
+  array = rb_ary_new2(m->number_of_matches - 1);
+  for (i = 1; i < m->number_of_matches; i++) {
+    match = &m->matches[i];
+
+    if (match->empty()) {
+      rb_ary_push(array, Qnil);
+    } else {
+      rb_ary_push(array, ENCODED_STR_NEW(match->data(), match->size(),
+            p->pattern->options().encoding() == RE2::Options::EncodingUTF8 ? "UTF-8" : "ISO-8859-1"));
+    }
+  }
+
+  return array;
+}
+
+/*
+ * Returns a hash of capturing group names to submatches for pattern matching.
+ *
+ * As this is used by Ruby's pattern matching, it will return an empty hash if given
+ * more keys than there are capturing groups. Given keys will populate the hash in
+ * order but an invalid name will cause the hash to be immediately returned.
+ *
+ * @return [Hash] a hash of capturing group names to submatches
+ * @param [Array<Symbol>, nil] keys an array of Symbol capturing group names or nil to return all names
+ * @example
+ *   m = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+ *   m.deconstruct_keys(nil)                  #=> {:numbers => "123", :letters => "abc"}
+ *   m.deconstruct_keys([:numbers])           #=> {:numbers => "123"}
+ *   m.deconstruct_keys([:fruit])             #=> {}
+ *   m.deconstruct_keys([:letters, :fruit])   #=> {:letters => "abc"}
+ *
+ * @example pattern matching
+ *   case RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+ *   in numbers:, letters:
+ *     puts "Numbers: #{numbers}, letters: #{letters}"
+ *   else
+ *     puts "Unrecognised match"
+ *   end
+ */
+static VALUE re2_matchdata_deconstruct_keys(VALUE self, VALUE keys) {
+  int i;
+  VALUE capturing_groups, key;
+  re2_matchdata *m;
+  re2_pattern *p;
+  map<string, int> groups;
+  map<string, int>::iterator iterator;
+
+  Data_Get_Struct(self, re2_matchdata, m);
+  Data_Get_Struct(m->regexp, re2_pattern, p);
+
+  groups = p->pattern->NamedCapturingGroups();
+  capturing_groups = rb_hash_new();
+
+  if (NIL_P(keys)) {
+    for (iterator = groups.begin(); iterator != groups.end(); iterator++) {
+      rb_hash_aset(capturing_groups,
+          ID2SYM(rb_intern(iterator->first.data())),
+          re2_matchdata_nth_match(iterator->second, self));
+    }
+  } else {
+    Check_Type(keys, T_ARRAY);
+
+    if (p->pattern->NumberOfCapturingGroups() >= RARRAY_LEN(keys)) {
+      for (i = 0; i < RARRAY_LEN(keys); i++) {
+        key = rb_ary_entry(keys, i);
+        Check_Type(key, T_SYMBOL);
+        string name(rb_id2name(SYM2ID(key)));
+
+        if (groups.count(name) == 0) {
+          break;
+        }
+
+        rb_hash_aset(capturing_groups, key, re2_matchdata_nth_match(groups[name], self));
+      }
+    }
+  }
+
+  return capturing_groups;
+}
+
 /*
  * Returns a new RE2 object with a compiled version of
- * +pattern+ stored inside. Equivalent to +RE2.new+.
+ * +pattern+ stored inside. Equivalent to +RE2::Regexp.new+.
  *
- * @return [RE2::Regexp] an RE2::Regexp with the specified pattern and options
- * @param [String] pattern the pattern to compile
- * @param [Hash] options the options to compile a regexp with
- * @see RE2::Regexp.new
+ * @see RE2::Regexp#initialize
  *
  */
 static VALUE re2_re2(int argc, VALUE *argv, VALUE self) {
@@ -727,7 +830,7 @@ static VALUE re2_re2(int argc, VALUE *argv, VALUE self) {
  *   @option options [Boolean] :posix_syntax (false) restrict regexps to POSIX egrep syntax
  *   @option options [Boolean] :longest_match (false) search for longest match, not first match
  *   @option options [Boolean] :log_errors (true) log syntax and execution errors to ERROR
- *   @option options [Fixnum] :max_mem approx. max memory footprint of RE2
+ *   @option options [Integer] :max_mem approx. max memory footprint of RE2
  *   @option options [Boolean] :literal (false) interpret string as literal, not regexp
  *   @option options [Boolean] :never_nl (false) never match \n, even if it is in regexp
  *   @option options [Boolean] :case_sensitive (true) match is case-sensitive (regexp can override with (?i) unless in posix_syntax mode)
@@ -878,7 +981,7 @@ static VALUE re2_regexp_log_errors(VALUE self) {
  * Returns the max_mem setting for the regular expression
  * +re2+.
  *
- * @return [Fixnum] the max_mem option
+ * @return [Integer] the max_mem option
  * @example
  *   re2 = RE2::Regexp.new("woo?", :max_mem => 1024)
  *   re2.max_mem    #=> 1024
@@ -1032,7 +1135,7 @@ static VALUE re2_regexp_error_arg(VALUE self) {
  * of a regexp's "cost". Larger numbers are more expensive
  * than smaller numbers.
  *
- * @return [Fixnum] the regexp "cost"
+ * @return [Integer] the regexp "cost"
  */
 static VALUE re2_regexp_program_size(VALUE self) {
   re2_pattern *p;
@@ -1097,7 +1200,7 @@ static VALUE re2_regexp_options(VALUE self) {
  * wasn't valid on construction. The overall match ($0) does not
  * count: if the regexp is "(a)(b)", returns 2.
  *
- * @return [Fixnum] the number of capturing subpatterns
+ * @return [Integer] the number of capturing subpatterns
  */
 static VALUE re2_regexp_number_of_capturing_groups(VALUE self) {
   re2_pattern *p;
@@ -1167,7 +1270,7 @@ static VALUE re2_regexp_named_capturing_groups(VALUE self) {
  *   matches returned (padded with nils if necessary).
  *
  *   @param [String] text the text to search
- *   @param [Fixnum] number_of_matches the number of matches to return
+ *   @param [Integer] number_of_matches the number of matches to return
  *   @return [RE2::MatchData] the matches
  *   @raise [ArgumentError] if given a negative number of matches
  *   @raise [NoMemoryError] if there was not enough memory to allocate the matches
@@ -1245,7 +1348,7 @@ static VALUE re2_regexp_match(int argc, VALUE *argv, VALUE self) {
  *
  * @return [Boolean] whether the match was successful
  */
-static VALUE re2_regexp_match_query(VALUE self, VALUE text) {
+static VALUE re2_regexp_match_p(VALUE self, VALUE text) {
   VALUE argv[2];
   argv[0] = text;
   argv[1] = INT2FIX(0);
@@ -1293,7 +1396,7 @@ static VALUE re2_regexp_scan(VALUE self, VALUE text) {
  * @return [String] the resulting string
  * @example
  *   RE2.Replace("hello there", "hello", "howdy") #=> "howdy there"
- *   re2 = RE2.new("hel+o")
+ *   re2 = RE2::Regexp.new("hel+o")
  *   RE2.Replace("hello there", re2, "yo")        #=> "yo there"
  */
 static VALUE re2_Replace(VALUE self, VALUE str, VALUE pattern,
@@ -1329,7 +1432,7 @@ static VALUE re2_Replace(VALUE self, VALUE str, VALUE pattern,
  * @param [String] rewrite the string to replace with
  * @return [String] the resulting string
  * @example
- *   re2 = RE2.new("oo?")
+ *   re2 = RE2::Regexp.new("oo?")
  *   RE2.GlobalReplace("whoops-doops", re2, "e")  #=> "wheps-deps"
  *   RE2.GlobalReplace("hello there", "e", "i")   #=> "hillo thiri"
  */
@@ -1416,7 +1519,7 @@ static VALUE re2_set_allocate(VALUE klass) {
  *   @option options [Boolean] :posix_syntax (false) restrict regexps to POSIX egrep syntax
  *   @option options [Boolean] :longest_match (false) search for longest match, not first match
  *   @option options [Boolean] :log_errors (true) log syntax and execution errors to ERROR
- *   @option options [Fixnum] :max_mem approx. max memory footprint of RE2
+ *   @option options [Integer] :max_mem approx. max memory footprint of RE2
  *   @option options [Boolean] :literal (false) interpret string as literal, not regexp
  *   @option options [Boolean] :never_nl (false) never match \n, even if it is in regexp
  *   @option options [Boolean] :case_sensitive (true) match is case-sensitive (regexp can override with (?i) unless in posix_syntax mode)
@@ -1514,6 +1617,7 @@ static VALUE re2_set_compile(VALUE self) {
  * @return [Bool] whether the underlying re2 outputs error information from Set matches
  */
 static VALUE re2_set_match_raises_errors_p(VALUE self) {
+  UNUSED(self);
 #ifdef HAVE_ERROR_INFO_ARGUMENT
   return Qtrue;
 #else
@@ -1526,18 +1630,40 @@ static VALUE re2_set_match_raises_errors_p(VALUE self) {
  * integer indices of the matching patterns if matched or an empty array if
  * there are no matches.
  *
- * @param [String] str the text to match against
- * @param [Hash] options the options with which to match
- * @option options [Boolean] :exception (true) whether to raise exceptions with re2's error information (not supported on ABI version 0 of re2)
- * @return [Array<Integer>] the indices of matching regexps
- * @raise [MatchError] if an error occurs while matching
- * @raise [UnsupportedError] if using the :exception option against a version of re2 that does not support it
- * @example
- *   set = RE2::Set.new
- *   set.add("abc")
- *   set.add("def")
- *   set.compile
- *   set.match("abcdef")    # => [0, 1]
+ * @return [Array<Integer>]
+ *
+ * @overload match(str)
+ *   Returns an array of integer indices of patterns matching the given string
+ *   (if any). Raises exceptions if there are any errors while matching.
+ *
+ *   @param [String] str the text to match against
+ *   @return [Array<Integer>] the indices of matching regexps
+ *   @raise [MatchError] if an error occurs while matching
+ *   @raise [UnsupportedError] if the underlying version of re2 does not output error information
+ *   @example
+ *     set = RE2::Set.new
+ *     set.add("abc")
+ *     set.add("def")
+ *     set.compile
+ *     set.match("abcdef")    # => [0, 1]
+ *
+ * @overload match(str, options)
+ *   Returns an array of integer indices of patterns matching the given string
+ *   (if any). Raises exceptions if there are any errors while matching and the
+ *   :exception option is set to true.
+ *
+ *   @param [String] str the text to match against
+ *   @param [Hash] options the options with which to match
+ *   @option options [Boolean] :exception (true) whether to raise exceptions with re2's error information (not supported on ABI version 0 of re2)
+ *   @return [Array<Integer>] the indices of matching regexps
+ *   @raise [MatchError] if an error occurs while matching
+ *   @raise [UnsupportedError] if the underlying version of re2 does not output error information
+ *   @example
+ *     set = RE2::Set.new
+ *     set.add("abc")
+ *     set.add("def")
+ *     set.compile
+ *     set.match("abcdef", :exception => true)    # => [0, 1]
  */
 static VALUE re2_set_match(int argc, VALUE *argv, VALUE self) {
   VALUE str, options, exception_option;
@@ -1644,6 +1770,10 @@ void Init_re2(void) {
         RUBY_METHOD_FUNC(re2_matchdata_to_s), 0);
   rb_define_method(re2_cMatchData, "inspect",
       RUBY_METHOD_FUNC(re2_matchdata_inspect), 0);
+  rb_define_method(re2_cMatchData, "deconstruct",
+      RUBY_METHOD_FUNC(re2_matchdata_deconstruct), 0);
+  rb_define_method(re2_cMatchData, "deconstruct_keys",
+      RUBY_METHOD_FUNC(re2_matchdata_deconstruct_keys), 1);
 
   rb_define_method(re2_cScanner, "string",
       RUBY_METHOD_FUNC(re2_scanner_string), 0);
@@ -1674,11 +1804,11 @@ void Init_re2(void) {
   rb_define_method(re2_cRegexp, "match", RUBY_METHOD_FUNC(re2_regexp_match),
       -1);
   rb_define_method(re2_cRegexp, "match?",
-      RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
+      RUBY_METHOD_FUNC(re2_regexp_match_p), 1);
   rb_define_method(re2_cRegexp, "=~",
-      RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
+      RUBY_METHOD_FUNC(re2_regexp_match_p), 1);
   rb_define_method(re2_cRegexp, "===",
-      RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
+      RUBY_METHOD_FUNC(re2_regexp_match_p), 1);
   rb_define_method(re2_cRegexp, "scan",
       RUBY_METHOD_FUNC(re2_regexp_scan), 1);
   rb_define_method(re2_cRegexp, "to_s", RUBY_METHOD_FUNC(re2_regexp_to_s), 0);
@@ -1756,9 +1886,4 @@ void Init_re2(void) {
   id_anchor_start = rb_intern("anchor_start");
   id_anchor_both = rb_intern("anchor_both");
   id_exception = rb_intern("exception");
-
-  #if 0
-    /* Fake so YARD generates the file. */
-    rb_mKernel = rb_define_module("Kernel");
-  #endif
 }

data/lib/re2/string.rb

@@ -12,30 +12,14 @@ module RE2
     # Replaces the first occurrence +pattern+ with +rewrite+ and returns a new
     # string.
     #
-    # @param [String, RE2::Regexp] pattern a regexp matching text to be replaced
-    # @param [String] rewrite the string to replace with
-    # @example
-    #   "hello there".re2_sub("hello", "howdy") #=> "howdy there"
-    #   re2 = RE2.new("hel+o")
-    #   "hello there".re2_sub(re2, "yo")        #=> "yo there"
-    #   text = "Good morning"
-    #   text.re2_sub("morn", "even")            #=> "Good evening"
-    #   text                                    #=> "Good morning"
+    # @see RE2.Replace
     def re2_sub(*args)
       RE2.Replace(self, *args)
     end
 
     # Replaces every occurrence of +pattern+ with +rewrite+ and return a new string.
     #
-    # @param [String, RE2::Regexp] pattern a regexp matching text to be replaced
-    # @param [String] rewrite the string to replace with
-    # @example
-    #   "hello there".re2_gsub("e", "i")   #=> "hillo thiri"
-    #   re2 = RE2.new("oo?")
-    #   "whoops-doops".re2_gsub(re2, "e")  #=> "wheps-deps"
-    #   text = "Good morning"
-    #   text.re2_gsub("o", "ee")           #=> "Geeeed meerning"
-    #   text                               #=> "Good morning"
+    # @see RE2.GlobalReplace
     def re2_gsub(*args)
       RE2.GlobalReplace(self, *args)
     end
@@ -74,7 +58,7 @@ module RE2
     #   matches returned (padded with nils if necessary).
     #
     #   @param [String, RE2::Regexp] pattern the regular expression to match
-    #   @param [Fixnum] number_of_matches the number of matches to return
+    #   @param [Integer] number_of_matches the number of matches to return
     #   @return [RE2::MatchData] the matches
     #   @raise [NoMemoryError] if there was not enough memory to allocate the matches
     #   @example

data/spec/re2/match_data_spec.rb

@@ -241,4 +241,62 @@ RSpec.describe RE2::MatchData do
       expect(md.end(:foo)).to be_nil
     end
   end
+
+  describe "#deconstruct" do
+    it "returns all capturing groups" do
+      md = RE2::Regexp.new('w(o)(o)').match('woo')
+
+      expect(md.deconstruct).to eq(['o', 'o'])
+    end
+
+    it "includes optional capturing groups as nil" do
+      md = RE2::Regexp.new('w(.)(.)(.)?').match('woo')
+
+      expect(md.deconstruct).to eq(['o', 'o', nil])
+    end
+  end
+
+  describe "#deconstruct_keys" do
+    it "returns all named captures if given nil" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.deconstruct_keys(nil)).to eq(:numbers => '123', :letters => 'abc')
+    end
+
+    it "returns only named captures if given names" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.deconstruct_keys([:numbers])).to eq(:numbers => '123')
+    end
+
+    it "returns named captures up until an invalid name is given" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.deconstruct_keys([:numbers, :punctuation])).to eq(:numbers => '123')
+    end
+
+    it "returns an empty hash if given more capture names than exist" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.deconstruct_keys([:numbers, :letters, :punctuation])).to eq({})
+    end
+
+    it "returns an empty hash if there are no named capturing groups" do
+      md = RE2::Regexp.new('(\d+) ([a-zA-Z]+)').match('123 abc')
+
+      expect(md.deconstruct_keys(nil)).to eq({})
+    end
+
+    it "raises an error if given a non-array of keys" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect { md.deconstruct_keys(0) }.to raise_error(TypeError)
+    end
+
+    it "raises an error if given keys as non-symbols" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect { md.deconstruct_keys([0]) }.to raise_error(TypeError)
+    end
+  end
 end

data/spec/re2/regexp_spec.rb

@@ -91,7 +91,8 @@ RSpec.describe RE2::Regexp do
   describe "#program_size" do
     it "returns a numeric value" do
       program_size = RE2::Regexp.new('w(o)(o)').program_size
-      expect(program_size).to be_a(Fixnum)
+
+      expect(program_size).to be_an(Integer)
     end
 
     it "returns -1 for an invalid pattern" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: re2
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Paul Mucur
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-16 00:00:00.000000000 Z
+date: 2023-07-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -80,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Ruby bindings to re2.