re2 2.24.0 → 2.26.0

data/lib/re2/string.rb

@@ -13,14 +13,14 @@ require "re2"
 module RE2
   # @deprecated Use methods on {RE2} and {RE2::Regexp} instead.
   module String
-    # @deprecated Use {RE2.Replace} instead.
+    # @deprecated Use {RE2.replace} instead.
     def re2_sub(*args)
-      RE2.Replace(self, *args)
+      RE2.replace(self, *args)
     end
 
-    # @deprecated Use {RE2.GlobalReplace} instead.
+    # @deprecated Use {RE2.global_replace} instead.
     def re2_gsub(*args)
-      RE2.GlobalReplace(self, *args)
+      RE2.global_replace(self, *args)
     end
 
     # @deprecated Use {RE2::Regexp#match} instead.
@@ -28,9 +28,9 @@ module RE2
       RE2::Regexp.new(pattern).match(self, *args)
     end
 
-    # @deprecated Use {RE2.QuoteMeta} instead.
+    # @deprecated Use {RE2.escape} instead.
     def re2_escape
-      RE2.QuoteMeta(self)
+      RE2.escape(self)
     end
 
     alias_method :re2_quote, :re2_escape

data/lib/re2/version.rb

@@ -10,5 +10,5 @@
 
 
 module RE2
-  VERSION = "2.24.0"
+  VERSION = "2.26.0"
 end

data/spec/re2/match_data_spec.rb

@@ -66,10 +66,16 @@ RSpec.describe RE2::MatchData do
       expect(a).to eq(["woo", "o", "o"])
     end
 
-    it "populates optional capturing groups with nil if they are missing" do
+    it "populates optional capturing groups with empty strings if they match zero characters" do
       a = RE2::Regexp.new('(\d?)(a)(b)').match('ab').to_a
 
-      expect(a).to eq(["ab", nil, "a", "b"])
+      expect(a).to eq(["ab", "", "a", "b"])
+    end
+
+    it "distinguishes between zero-length matches and unmatched groups" do
+      a = RE2::Regexp.new('()(a)?').match('b').to_a
+
+      expect(a).to eq(["", "", nil])
     end
 
     it "returns UTF-8 strings if the pattern is UTF-8" do
@@ -158,6 +164,12 @@ RSpec.describe RE2::MatchData do
       expect(md[:numbers]).to eq("123")
     end
 
+    it "returns an empty string for a zero-length capturing group" do
+      md = RE2::Regexp.new('()').match("bob")
+
+      expect(md[1]).to eq("")
+    end
+
     it "returns nil if no such named group exists", :aggregate_failures do
       md = RE2::Regexp.new('(\d+)').match("bob 123")
 
@@ -281,6 +293,12 @@ RSpec.describe RE2::MatchData do
       expect(md.inspect).to eq('#<RE2::MatchData "1234 " 1:"1234" 2:nil>')
     end
 
+    it "represents zero-length capturing groups as empty strings" do
+      md = RE2::Regexp.new('()').match("bob")
+
+      expect(md.inspect).to eq('#<RE2::MatchData "" 1:"">')
+    end
+
     it "supports matches with null bytes" do
       md = RE2::Regexp.new("(\\w\0\\w) (\\w\0\\w)").match("a\0b c\0d")
 
@@ -299,6 +317,12 @@ RSpec.describe RE2::MatchData do
       expect(md.to_s).to eq("23456")
     end
 
+    it "returns an empty string for a zero-length match" do
+      md = RE2::Regexp.new('()').match("bob")
+
+      expect(md.to_s).to eq("")
+    end
+
     it "raises an error when called on an uninitialized object" do
       expect { described_class.allocate.to_s }.to raise_error(TypeError, /uninitialized RE2::MatchData/)
     end
@@ -346,6 +370,12 @@ RSpec.describe RE2::MatchData do
       expect(md.string[md.begin(0)..-1]).to eq('Ruby')
     end
 
+    it "returns the offset for a zero-length capturing group" do
+      md = RE2::Regexp.new('()').match("bob")
+
+      expect(md.begin(1)).to eq(0)
+    end
+
     it "returns nil for non-existent numerical matches" do
       md = RE2::Regexp.new('(\d)').match('123')
 
@@ -419,6 +449,12 @@ RSpec.describe RE2::MatchData do
       expect(md.string[0...md.end(0)]).to eq('I ♥ Ruby')
     end
 
+    it "returns the offset for a zero-length capturing group" do
+      md = RE2::Regexp.new('()').match("bob")
+
+      expect(md.end(1)).to eq(0)
+    end
+
     it "returns nil for non-existent numerical matches" do
       md = RE2::Regexp.new('(\d)').match('123')
 
@@ -461,6 +497,264 @@ RSpec.describe RE2::MatchData do
     end
   end
 
+  describe "#pre_match" do
+    it "returns the portion of the string before the match" do
+      md = RE2::Regexp.new('(\d+)').match("bob 123 456")
+
+      expect(md.pre_match).to eq("bob ")
+    end
+
+    it "returns an empty string when the match starts at the beginning" do
+      md = RE2::Regexp.new('(\w+)').match("bob 123")
+
+      expect(md.pre_match).to eq("")
+    end
+
+    it "supports multibyte characters" do
+      md = RE2::Regexp.new('(\d+)').match("I ♥ 123")
+
+      expect(md.pre_match).to eq("I ♥ ")
+    end
+
+    it "returns UTF-8 strings by default" do
+      md = RE2::Regexp.new('(\d+)').match("abc 123")
+
+      expect(md.pre_match.encoding).to eq(Encoding::UTF_8)
+    end
+
+    it "returns ISO-8859-1 strings if the pattern is not UTF-8" do
+      md = RE2::Regexp.new('(\d+)', utf8: false).match("abc 123")
+
+      expect(md.pre_match.encoding).to eq(Encoding::ISO_8859_1)
+    end
+
+    it "returns the text before a zero-length match" do
+      md = RE2::Regexp.new('()').match("bob")
+
+      expect(md.pre_match).to eq("")
+    end
+
+    it "raises an error when called on an uninitialized object" do
+      expect { described_class.allocate.pre_match }.to raise_error(TypeError, /uninitialized RE2::MatchData/)
+    end
+  end
+
+  describe "#post_match" do
+    it "returns the portion of the string after the match" do
+      md = RE2::Regexp.new('(\d+)').match("bob 123 456")
+
+      expect(md.post_match).to eq(" 456")
+    end
+
+    it "returns an empty string when the match ends at the end" do
+      md = RE2::Regexp.new('(\d+)$').match("bob 123")
+
+      expect(md.post_match).to eq("")
+    end
+
+    it "supports multibyte characters" do
+      md = RE2::Regexp.new('(\d+)').match("123 ♥ world")
+
+      expect(md.post_match).to eq(" ♥ world")
+    end
+
+    it "returns UTF-8 strings by default" do
+      md = RE2::Regexp.new('(\d+)').match("abc 123 def")
+
+      expect(md.post_match.encoding).to eq(Encoding::UTF_8)
+    end
+
+    it "returns ISO-8859-1 strings if the pattern is not UTF-8" do
+      md = RE2::Regexp.new('(\d+)', utf8: false).match("abc 123 def")
+
+      expect(md.post_match.encoding).to eq(Encoding::ISO_8859_1)
+    end
+
+    it "returns the text after a zero-length match" do
+      md = RE2::Regexp.new('()').match("bob")
+
+      expect(md.post_match).to eq("bob")
+    end
+
+    it "raises an error when called on an uninitialized object" do
+      expect { described_class.allocate.post_match }.to raise_error(TypeError, /uninitialized RE2::MatchData/)
+    end
+  end
+
+  describe "#offset" do
+    it "returns the offset of a match by index" do
+      md = RE2::Regexp.new('ob (\d+)').match("bob 123")
+
+      expect(md.offset(0)).to eq([1, 7])
+    end
+
+    it "returns the offset of a submatch by index" do
+      md = RE2::Regexp.new('ob (\d+)').match("bob 123")
+
+      expect(md.offset(1)).to eq([4, 7])
+    end
+
+    it "returns the offset of a match by string name" do
+      md = RE2::Regexp.new('(?P<number>\d+)').match("bob 123")
+
+      expect(md.offset("number")).to eq([4, 7])
+    end
+
+    it "returns the offset of a match by symbol name" do
+      md = RE2::Regexp.new('(?P<number>\d+)').match("bob 123")
+
+      expect(md.offset(:number)).to eq([4, 7])
+    end
+
+    it "returns character offsets despite multibyte characters" do
+      md = RE2::Regexp.new('(Ruby)').match("I ♥ Ruby")
+
+      expect(md.offset(0)).to eq([4, 8])
+    end
+
+    it "returns identical offsets for a zero-length capturing group" do
+      md = RE2::Regexp.new('()').match("bob")
+
+      expect(md.offset(1)).to eq([0, 0])
+    end
+
+    it "returns nil for non-existent numerical matches" do
+      md = RE2::Regexp.new('(\d)').match("123")
+
+      expect(md.offset(10)).to be_nil
+    end
+
+    it "returns nil for non-existent named matches" do
+      md = RE2::Regexp.new('(\d)').match("123")
+
+      expect(md.offset("foo")).to be_nil
+    end
+
+    it "raises a type error if given an invalid name or number" do
+      md = RE2::Regexp.new('(\d)').match("123")
+
+      expect { md.offset(nil) }.to raise_error(TypeError)
+    end
+
+    it "raises an error when called on an uninitialized object" do
+      expect { described_class.allocate.offset(0) }.to raise_error(TypeError, /uninitialized RE2::MatchData/)
+    end
+  end
+
+  describe "#match_length" do
+    it "returns the length of the overall match" do
+      md = RE2::Regexp.new('ob (\d+)').match("bob 123")
+
+      expect(md.match_length(0)).to eq(6)
+    end
+
+    it "returns the length of a submatch by index" do
+      md = RE2::Regexp.new('ob (\d+)').match("bob 123")
+
+      expect(md.match_length(1)).to eq(3)
+    end
+
+    it "returns the length of a match by string name" do
+      md = RE2::Regexp.new('(?P<number>\d+)').match("bob 123")
+
+      expect(md.match_length("number")).to eq(3)
+    end
+
+    it "returns the length of a match by symbol name" do
+      md = RE2::Regexp.new('(?P<number>\d+)').match("bob 123")
+
+      expect(md.match_length(:number)).to eq(3)
+    end
+
+    it "returns character length despite multibyte characters" do
+      md = RE2::Regexp.new('(♥ Ruby)').match("I ♥ Ruby!")
+
+      expect(md.match_length(0)).to eq(6)
+    end
+
+    it "returns zero for a zero-length capturing group" do
+      md = RE2::Regexp.new('()').match("bob")
+
+      expect(md.match_length(1)).to eq(0)
+    end
+
+    it "returns nil for non-existent numerical matches" do
+      md = RE2::Regexp.new('(\d)').match("123")
+
+      expect(md.match_length(10)).to be_nil
+    end
+
+    it "returns nil for non-existent named matches" do
+      md = RE2::Regexp.new('(\d)').match("123")
+
+      expect(md.match_length("foo")).to be_nil
+    end
+
+    it "raises a type error if given an invalid name or number" do
+      md = RE2::Regexp.new('(\d)').match("123")
+
+      expect { md.match_length(nil) }.to raise_error(TypeError)
+    end
+
+    it "raises an error when called on an uninitialized object" do
+      expect { described_class.allocate.match_length(0) }.to raise_error(TypeError, /uninitialized RE2::MatchData/)
+    end
+  end
+
+  describe "#values_at" do
+    it "returns match values at the given indices" do
+      md = RE2::Regexp.new('(\d+) (\d+) (\d+)').match("123 456 789")
+
+      expect(md.values_at(1, 3)).to eq(["123", "789"])
+    end
+
+    it "returns match values by named groups" do
+      md = RE2::Regexp.new('(?P<a>\d+) (?P<b>\d+)').match("123 456")
+
+      expect(md.values_at(:a, :b)).to eq(["123", "456"])
+    end
+
+    it "supports a mix of indices and names" do
+      md = RE2::Regexp.new('(?P<a>\d+) (\d+)').match("123 456")
+
+      expect(md.values_at(2, :a)).to eq(["456", "123"])
+    end
+
+    it "returns nil for non-existent indices" do
+      md = RE2::Regexp.new('(\d+)').match("123")
+
+      expect(md.values_at(1, 5)).to eq(["123", nil])
+    end
+
+    it "returns nil for non-existent names" do
+      md = RE2::Regexp.new('(?P<a>\d+)').match("123")
+
+      expect(md.values_at(:a, :z)).to eq(["123", nil])
+    end
+
+    it "returns an empty string for a zero-length capturing group" do
+      md = RE2::Regexp.new('()(b)').match("bob")
+
+      expect(md.values_at(1, 2)).to eq(["", "b"])
+    end
+
+    it "returns the full match when given index 0" do
+      md = RE2::Regexp.new('(\d+) (\d+)').match("123 456")
+
+      expect(md.values_at(0, 1)).to eq(["123 456", "123"])
+    end
+
+    it "returns an empty array if given no arguments" do
+      md = RE2::Regexp.new('(\d+) (\d+)').match("123 456")
+
+      expect(md.values_at).to be_empty
+    end
+
+    it "raises an error when called on an uninitialized object" do
+      expect { described_class.allocate.values_at(1) }.to raise_error(TypeError, /uninitialized RE2::MatchData/)
+    end
+  end
+
   describe "#deconstruct" do
     it "returns all capturing groups" do
       md = RE2::Regexp.new('w(o)(o)').match('woo')
@@ -474,11 +768,107 @@ RSpec.describe RE2::MatchData do
       expect(md.deconstruct).to eq(['o', 'o', nil])
     end
 
+    it "includes zero-length capturing groups as empty strings" do
+      md = RE2::Regexp.new('()').match("bob")
+
+      expect(md.deconstruct).to eq([""])
+    end
+
     it "raises an error when called on an uninitialized object" do
       expect { described_class.allocate.deconstruct }.to raise_error(TypeError, /uninitialized RE2::MatchData/)
     end
   end
 
+  describe "#captures" do
+    it "returns all capturing groups" do
+      md = RE2::Regexp.new('w(o)(o)').match('woo')
+
+      expect(md.captures).to eq(['o', 'o'])
+    end
+
+    it "includes optional capturing groups as nil" do
+      md = RE2::Regexp.new('w(.)(.)(.)?').match('woo')
+
+      expect(md.captures).to eq(['o', 'o', nil])
+    end
+
+    it "raises an error when called on an uninitialized object" do
+      expect { described_class.allocate.captures }.to raise_error(TypeError, /uninitialized RE2::MatchData/)
+    end
+  end
+
+  describe "#named_captures" do
+    it "returns a hash of capturing group names to matched strings" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.named_captures).to eq("numbers" => "123", "letters" => "abc")
+    end
+
+    it "returns an empty hash if there are no named capturing groups" do
+      md = RE2::Regexp.new('(\d+)').match('123')
+
+      expect(md.named_captures).to be_empty
+    end
+
+    it "returns unmatched optional groups as nil" do
+      md = RE2::Regexp.new('(?P<a>\d+) (?P<b>\w+)?').match('123 ')
+
+      expect(md.named_captures).to eq("a" => "123", "b" => nil)
+    end
+
+    it "returns an empty string for a zero-length named capturing group" do
+      md = RE2::Regexp.new('(?P<empty>)(?P<word>\w+)').match("bob")
+
+      expect(md.named_captures).to eq("empty" => "", "word" => "bob")
+    end
+
+    it "returns symbol keys when symbolize_names: true" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.named_captures(symbolize_names: true)).to eq(numbers: "123", letters: "abc")
+    end
+
+    it "returns string keys when symbolize_names: false" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.named_captures(symbolize_names: false)).to eq("numbers" => "123", "letters" => "abc")
+    end
+
+    it "raises an error when called on an uninitialized object" do
+      expect { described_class.allocate.named_captures }.to raise_error(TypeError, /uninitialized RE2::MatchData/)
+    end
+  end
+
+  describe "#names" do
+    it "returns an array of names of named capturing groups" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.names).to eq(["letters", "numbers"])
+    end
+
+    it "returns an empty array if there are no named capturing groups" do
+      md = RE2::Regexp.new('(\d+)').match('123')
+
+      expect(md.names).to be_empty
+    end
+
+    it "returns UTF-8 strings if the pattern is UTF-8" do
+      md = RE2::Regexp.new('(?P<numbers>\d+)').match('123')
+
+      expect(md.names.first.encoding).to eq(Encoding::UTF_8)
+    end
+
+    it "returns ISO-8859-1 strings if the pattern is not UTF-8" do
+      md = RE2::Regexp.new('(?P<numbers>\d+)', utf8: false).match('123')
+
+      expect(md.names.first.encoding).to eq(Encoding::ISO_8859_1)
+    end
+
+    it "raises an error when called on an uninitialized object" do
+      expect { described_class.allocate.names }.to raise_error(TypeError, /uninitialized RE2::MatchData/)
+    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')
@@ -510,6 +900,12 @@ RSpec.describe RE2::MatchData do
       expect(md.deconstruct_keys(nil)).to eq({})
     end
 
+    it "returns an empty string for a zero-length named capturing group" do
+      md = RE2::Regexp.new('(?P<empty>)(?P<word>\w+)').match("bob")
+
+      expect(md.deconstruct_keys(nil)).to eq(empty: "", word: "bob")
+    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')
 

data/spec/re2/regexp_spec.rb

@@ -723,7 +723,6 @@ RSpec.describe RE2::Regexp do
 
     it "raises an exception if given too large a number of submatches instead of options" do
       re = RE2::Regexp.new('(\w+) (\w+) (\w+)')
-      md = re.match("one two three", 2)
 
       expect { re.match("one two three", INT_MAX) }.to raise_error(RangeError, "number of matches should be < #{INT_MAX}")
     end
@@ -963,6 +962,64 @@ RSpec.describe RE2::Regexp do
     end
   end
 
+  describe "#names" do
+    it "returns an array of names of named capturing groups" do
+      expect(RE2::Regexp.new('(?P<bob>a)(?P<rob>b)').names).to eq(["bob", "rob"])
+    end
+
+    it "returns an empty array if there are no named capturing groups" do
+      expect(RE2::Regexp.new('(a)(b)').names).to be_empty
+    end
+
+    it "returns an empty array for a pattern with no capturing groups" do
+      expect(RE2::Regexp.new('ab').names).to be_empty
+    end
+
+    it "returns an empty array for an invalid regexp" do
+      expect(RE2::Regexp.new('???', log_errors: false).names).to be_empty
+    end
+
+    it "returns UTF-8 strings if the pattern is UTF-8" do
+      names = RE2::Regexp.new('(?P<bob>a)').names
+
+      expect(names.first.encoding).to eq(Encoding::UTF_8)
+    end
+
+    it "returns ISO-8859-1 strings if the pattern is not UTF-8" do
+      names = RE2::Regexp.new('(?P<bob>a)', utf8: false).names
+
+      expect(names.first.encoding).to eq(Encoding::ISO_8859_1)
+    end
+
+    it "raises an error when called on an uninitialized object" do
+      expect { described_class.allocate.names }.to raise_error(TypeError, /uninitialized RE2::Regexp/)
+    end
+  end
+
+  describe "#named_captures" do
+    it "returns a hash of names to indices" do
+      expect(RE2::Regexp.new('(?P<bob>a)').named_captures).to eq("bob" => 1)
+    end
+
+    it "maps names to indices with several groups" do
+      groups = RE2::Regexp.new('(?P<bob>a)(o)(?P<rob>e)').named_captures
+
+      expect(groups).to eq("bob" => 1, "rob" => 3)
+    end
+
+    it "returns an empty hash for a pattern with no named groups" do
+      expect(RE2::Regexp.new('(a)(b)').named_captures).to be_empty
+    end
+
+    it "returns an empty hash for an invalid regexp" do
+      expect(RE2::Regexp.new('???', log_errors: false).named_captures).to be_empty
+    end
+
+    it "raises an error when called on an uninitialized object" do
+      expect { described_class.allocate.named_captures }.to raise_error(TypeError, /uninitialized RE2::Regexp/)
+    end
+  end
+
   describe "#scan" do
     it "returns a scanner" do
       r = RE2::Regexp.new('(\w+)')

data/spec/re2/scanner_spec.rb

@@ -185,11 +185,11 @@ RSpec.describe RE2::Scanner do
       expect(scanner.scan).to be_nil
     end
 
-    it "returns an array of nil with an empty input and capture", :aggregate_failures do
+    it "returns an array of empty strings with an empty input and capture", :aggregate_failures do
       r = RE2::Regexp.new("()")
       scanner = r.scan("")
 
-      expect(scanner.scan).to eq([nil])
+      expect(scanner.scan).to eq([""])
       expect(scanner.scan).to be_nil
     end
 
@@ -204,25 +204,34 @@ RSpec.describe RE2::Scanner do
       expect(scanner.scan).to be_nil
     end
 
-    it "returns an array of nil if the pattern is an empty capturing group", :aggregate_failures do
+    it "returns an array of empty strings if the pattern is an empty capturing group", :aggregate_failures do
       r = RE2::Regexp.new("()")
       scanner = r.scan("Foo")
 
-      expect(scanner.scan).to eq([nil])
-      expect(scanner.scan).to eq([nil])
-      expect(scanner.scan).to eq([nil])
-      expect(scanner.scan).to eq([nil])
+      expect(scanner.scan).to eq([""])
+      expect(scanner.scan).to eq([""])
+      expect(scanner.scan).to eq([""])
+      expect(scanner.scan).to eq([""])
       expect(scanner.scan).to be_nil
     end
 
-    it "returns array of nils with multiple empty capturing groups", :aggregate_failures do
+    it "returns array of empty strings with multiple empty capturing groups", :aggregate_failures do
       r = RE2::Regexp.new("()()()")
       scanner = r.scan("Foo")
 
-      expect(scanner.scan).to eq([nil, nil, nil])
-      expect(scanner.scan).to eq([nil, nil, nil])
-      expect(scanner.scan).to eq([nil, nil, nil])
-      expect(scanner.scan).to eq([nil, nil, nil])
+      expect(scanner.scan).to eq(["", "", ""])
+      expect(scanner.scan).to eq(["", "", ""])
+      expect(scanner.scan).to eq(["", "", ""])
+      expect(scanner.scan).to eq(["", "", ""])
+      expect(scanner.scan).to be_nil
+    end
+
+    it "distinguishes zero-length matches from unmatched groups", :aggregate_failures do
+      r = RE2::Regexp.new("()(a)?")
+      scanner = r.scan("b")
+
+      expect(scanner.scan).to eq(["", nil])
+      expect(scanner.scan).to eq(["", nil])
       expect(scanner.scan).to be_nil
     end
 
@@ -230,7 +239,7 @@ RSpec.describe RE2::Scanner do
       r = RE2::Regexp.new("()€")
       scanner = r.scan("€")
 
-      expect(scanner.scan).to eq([nil])
+      expect(scanner.scan).to eq([""])
       expect(scanner.scan).to be_nil
     end