re2 2.4.3-x86_64-darwin → 2.6.0.rc1-x86_64-darwin

data/ext/re2/re2.cc

@@ -1,8 +1,10 @@
 /*
- * re2 (http://github.com/mudge/re2)
- * Ruby bindings to re2, an "efficient, principled regular expression library"
+ * re2 (https://github.com/mudge/re2)
+ * Ruby bindings to RE2, a "fast, safe, thread-friendly alternative to
+ * backtracking regular expression engines like those used in PCRE, Perl, and
+ * Python".
  *
- * Copyright (c) 2010-2014, Paul Mucur (http://mudge.name)
+ * Copyright (c) 2010, Paul Mucur (https://mudge.name)
  * Released under the BSD Licence, please see LICENSE.txt
  */
 
@@ -42,13 +44,14 @@ typedef struct {
 } re2_set;
 
 VALUE re2_mRE2, re2_cRegexp, re2_cMatchData, re2_cScanner, re2_cSet,
-      re2_eSetMatchError, re2_eSetUnsupportedError;
+      re2_eSetMatchError, re2_eSetUnsupportedError, re2_eRegexpUnsupportedError;
 
 /* Symbols used in RE2 options. */
 static ID id_utf8, id_posix_syntax, id_longest_match, id_log_errors,
           id_max_mem, id_literal, id_never_nl, id_case_sensitive,
-          id_perl_classes, id_word_boundary, id_one_line,
-          id_unanchored, id_anchor_start, id_anchor_both, id_exception;
+          id_perl_classes, id_word_boundary, id_one_line, id_unanchored,
+          id_anchor, id_anchor_start, id_anchor_both, id_exception,
+          id_submatches, id_startpos, id_endpos;
 
 inline VALUE encoded_str_new(const char *str, long length, RE2::Options::Encoding encoding) {
   if (encoding == RE2::Options::EncodingUTF8) {
@@ -122,7 +125,7 @@ static void parse_re2_options(RE2::Options* re2_options, const VALUE options) {
   }
 }
 
-/* For compatibility with ruby < 2.7 */
+/* For compatibility with Ruby < 2.7 */
 #ifdef HAVE_RB_GC_MARK_MOVABLE
 #define re2_compact_callback(x) (x),
 #else
@@ -270,12 +273,14 @@ static VALUE re2_scanner_allocate(VALUE klass) {
 }
 
 /*
- * Returns a frozen copy of the string passed into +match+.
+ * Returns a frozen copy of the text supplied when matching.
  *
- * @return [String] a frozen copy of the passed string.
+ * If the text was already a frozen string, returns the original.
+ *
+ * @return [String] a frozen string with the text supplied when matching
  * @example
- *   m = RE2::Regexp.new('(\d+)').match("bob 123")
- *   m.string  #=> "bob 123"
+ *   m = RE2::Regexp.new('(\d+)').partial_match("bob 123")
+ *   m.string #=> "bob 123"
  */
 static VALUE re2_matchdata_string(const VALUE self) {
   re2_matchdata *m;
@@ -285,9 +290,10 @@ static VALUE re2_matchdata_string(const VALUE self) {
 }
 
 /*
- * Returns the string passed into the scanner.
+ * Returns the text supplied when incrementally matching with
+ * {RE2::Regexp#scan}.
  *
- * @return [String] the original string.
+ * @return [String] the original string passed to {RE2::Regexp#scan}
  * @example
  *   c = RE2::Regexp.new('(\d+)').scan("foo")
  *   c.string #=> "foo"
@@ -300,9 +306,9 @@ static VALUE re2_scanner_string(const VALUE self) {
 }
 
 /*
- * Returns whether the scanner has consumed all input or not.
+ * Returns whether the {RE2::Scanner} has consumed all input or not.
  *
- * @return [Boolean] whether the scanner has consumed all input or not
+ * @return [Boolean] whether the {RE2::Scanner} has consumed all input or not
  * @example
  *   c = RE2::Regexp.new('(\d+)').scan("foo")
  *   c.eof? #=> true
@@ -315,7 +321,7 @@ static VALUE re2_scanner_eof(const VALUE self) {
 }
 
 /*
- * Rewind the scanner to the start of the string.
+ * Rewind the {RE2::Scanner} to the start of the string.
  *
  * @example
  *   s = RE2::Regexp.new('(\d+)').scan("1 2 3")
@@ -337,14 +343,19 @@ static VALUE re2_scanner_rewind(VALUE self) {
 }
 
 /*
- * Scan the given text incrementally for matches, returning an array of
- * matches on each subsequent call. Returns nil if no matches are found.
+ * Scan the given text incrementally for matches using
+ * {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/re2.h#L447-L463
+ * `FindAndConsume`}, returning an array of submatches on each subsequent
+ * call. Returns `nil` if no matches are found or an empty array for every
+ * match if the pattern has no capturing groups.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is undefined).
  *
- * @return [Array<String>] the matches.
+ * @return [Array<String>] if the pattern has capturing groups
+ * @return [[]] if the pattern does not have capturing groups
+ * @return [nil] if no matches are found
  * @example
  *   s = RE2::Regexp.new('(\w+)').scan("Foo bar baz")
  *   s.scan #=> ["Foo"]
@@ -359,7 +370,7 @@ static VALUE re2_scanner_scan(VALUE self) {
 
   std::vector<RE2::Arg> argv(c->number_of_capturing_groups);
   std::vector<RE2::Arg*> args(c->number_of_capturing_groups);
-  std::vector<std::string> matches(c->number_of_capturing_groups);
+  std::vector<re2::StringPiece> matches(c->number_of_capturing_groups);
 
   if (c->eof) {
     return Qnil;
@@ -403,9 +414,6 @@ static VALUE re2_scanner_scan(VALUE self) {
   }
 }
 
-/*
- * Retrieve a matchdata by index or name.
- */
 static re2::StringPiece *re2_matchdata_find_match(VALUE idx, const VALUE self) {
   re2_matchdata *m;
   re2_pattern *p;
@@ -441,13 +449,14 @@ static re2::StringPiece *re2_matchdata_find_match(VALUE idx, const VALUE self) {
 }
 
 /*
- * Returns the number of elements in the match array (including nils).
+ * Returns the number of elements in the {RE2::MatchData} (including the
+ * overall match, submatches and any `nils`).
  *
  * @return [Integer] the number of elements
  * @example
  *   m = RE2::Regexp.new('(\d+)').match("bob 123")
- *   m.size      #=> 2
- *   m.length    #=> 2
+ *   m.size   #=> 2
+ *   m.length #=> 2
  */
 static VALUE re2_matchdata_size(const VALUE self) {
   re2_matchdata *m;
@@ -458,14 +467,15 @@ static VALUE re2_matchdata_size(const VALUE self) {
 }
 
 /*
- * Returns the offset of the start of the nth element of the matchdata.
+ * Returns the offset of the start of the nth element of the {RE2::MatchData}.
  *
- * @param [Integer, String, Symbol] n the name or number of the match
- * @return [Integer] the offset of the start of the match
+ * @param [Integer, String, Symbol] n the name or number of the submatch
+ * @return [Integer, nil] the offset of the start of the match or `nil` if
+ *   there is no such submatch
  * @example
  *   m = RE2::Regexp.new('ob (\d+)').match("bob 123")
- *   m.begin(0)  #=> 1
- *   m.begin(1)  #=> 4
+ *   m.begin(0) #=> 1
+ *   m.begin(1) #=> 4
  */
 static VALUE re2_matchdata_begin(const VALUE self, VALUE n) {
   re2_matchdata *m;
@@ -483,14 +493,16 @@ static VALUE re2_matchdata_begin(const VALUE self, VALUE n) {
 }
 
 /*
- * Returns the offset of the character following the end of the nth element of the matchdata.
+ * Returns the offset of the character following the end of the nth element of
+ * the {RE2::MatchData}.
  *
  * @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
+ * @return [Integer, nil] the offset of the character following the end of the
+ *   match or `nil` if there is no such match
  * @example
  *   m = RE2::Regexp.new('ob (\d+) b').match("bob 123 bob")
- *   m.end(0)  #=> 9
- *   m.end(1)  #=> 7
+ *   m.end(0) #=> 9
+ *   m.end(1) #=> 7
  */
 static VALUE re2_matchdata_end(const VALUE self, VALUE n) {
   re2_matchdata *m;
@@ -510,10 +522,10 @@ static VALUE re2_matchdata_end(const VALUE self, VALUE n) {
 /*
  * Returns the {RE2::Regexp} used in the match.
  *
- * @return [RE2::Regexp] the regexp used in the match
+ * @return [RE2::Regexp] the regular expression used in the match
  * @example
  *   m = RE2::Regexp.new('(\d+)').match("bob 123")
- *   m.regexp    #=> #<RE2::Regexp /(\d+)/>
+ *   m.regexp #=> #<RE2::Regexp /(\d+)/>
  */
 static VALUE re2_matchdata_regexp(const VALUE self) {
   re2_matchdata *m;
@@ -523,12 +535,12 @@ static VALUE re2_matchdata_regexp(const VALUE self) {
 }
 
 /*
- * Returns the {RE2::Regexp} used in the scanner.
+ * Returns the {RE2::Regexp} used in the {RE2::Scanner}.
  *
- * @return [RE2::Regexp] the regexp used in the scanner
+ * @return [RE2::Regexp] the regular expression used in the {RE2::Scanner}
  * @example
  *   c = RE2::Regexp.new('(\d+)').scan("bob 123")
- *   c.regexp    #=> #<RE2::Regexp /(\d+)/>
+ *   c.regexp #=> #<RE2::Regexp /(\d+)/>
  */
 static VALUE re2_scanner_regexp(const VALUE self) {
   re2_scanner *c;
@@ -544,16 +556,17 @@ static VALUE re2_regexp_allocate(VALUE klass) {
 }
 
 /*
- * Returns the array of matches.
+ * Returns the array of matches including the overall match, submatches and any
+ * `nil`s.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is undefined).
  *
  * @return [Array<String, nil>] the array of matches
  * @example
  *   m = RE2::Regexp.new('(\d+)').match("bob 123")
- *   m.to_a    #=> ["123", "123"]
+ *   m.to_a #=> ["123", "123"]
  */
 static VALUE re2_matchdata_to_a(const VALUE self) {
   re2_matchdata *m;
@@ -619,19 +632,17 @@ static VALUE re2_matchdata_named_match(const char* name, const VALUE self) {
  * Retrieve zero, one or more matches by index or name.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
- *
- * @return [Array<String, nil>, String, Boolean]
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is undefined).
  *
  * @overload [](index)
  *   Access a particular match by index.
  *
  *   @param [Integer] index the index of the match to fetch
- *   @return [String, nil] the specified match
+ *   @return [String, nil] the specified match or `nil` if it isn't present
  *   @example
  *     m = RE2::Regexp.new('(\d+)').match("bob 123")
- *     m[0]    #=> "123"
+ *     m[0] #=> "123"
  *
  * @overload [](start, length)
  *   Access a range of matches by starting index and length.
@@ -641,7 +652,7 @@ static VALUE re2_matchdata_named_match(const char* name, const VALUE self) {
  *   @return [Array<String, nil>] the specified matches
  *   @example
  *     m = RE2::Regexp.new('(\d+)').match("bob 123")
- *     m[0, 1]    #=> ["123"]
+ *     m[0, 1] #=> ["123"]
  *
  * @overload [](range)
  *   Access a range of matches by index.
@@ -650,13 +661,13 @@ static VALUE re2_matchdata_named_match(const char* name, const VALUE self) {
  *   @return [Array<String, nil>] the specified matches
  *   @example
  *     m = RE2::Regexp.new('(\d+)').match("bob 123")
- *     m[0..1]    #=> "[123", "123"]
+ *     m[0..1] #=> "[123", "123"]
  *
  * @overload [](name)
  *   Access a particular match by name.
  *
  *   @param [String, Symbol] name the name of the match to fetch
- *   @return [String, nil] the specific match
+ *   @return [String, nil] the specific match or `nil` if it isn't present
  *   @example
  *     m = RE2::Regexp.new('(?P<number>\d+)').match("bob 123")
  *     m["number"] #=> "123"
@@ -690,13 +701,13 @@ static VALUE re2_matchdata_to_s(const VALUE self) {
  * Returns a printable version of the match.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is undefined).
  *
  * @return [String] a printable version of the match
  * @example
  *   m = RE2::Regexp.new('(\d+)').match("bob 123")
- *   m.inspect    #=> "#<RE2::MatchData \"123\" 1:\"123\">"
+ *   m.inspect #=> "#<RE2::MatchData \"123\" 1:\"123\">"
  */
 static VALUE re2_matchdata_inspect(const VALUE self) {
   re2_matchdata *m;
@@ -734,13 +745,14 @@ static VALUE re2_matchdata_inspect(const VALUE self) {
  * Returns the array of submatches for pattern matching.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is
+ * undefined).
  *
  * @return [Array<String, nil>] the array of submatches
  * @example
  *   m = RE2::Regexp.new('(\d+)').match("bob 123")
- *   m.deconstruct    #=> ["123"]
+ *   m.deconstruct #=> ["123"]
  *
  * @example pattern matching
  *   case RE2::Regexp.new('(\d+) (\d+)').match("bob 123 456")
@@ -780,17 +792,18 @@ static VALUE re2_matchdata_deconstruct(const VALUE self) {
  * order but an invalid name will cause the hash to be immediately returned.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is undefined).
  *
  * @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
+ * @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"}
+ *   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')
@@ -839,11 +852,9 @@ static VALUE re2_matchdata_deconstruct_keys(const VALUE self, const VALUE keys)
 }
 
 /*
- * Returns a new RE2 object with a compiled version of
- * +pattern+ stored inside. Equivalent to +RE2::Regexp.new+.
+ * Shorthand to compile a new {RE2::Regexp}.
  *
  * @see RE2::Regexp#initialize
- *
  */
 static VALUE re2_re2(int argc, VALUE *argv, VALUE) {
   return rb_class_new_instance(argc, argv, re2_cRegexp);
@@ -851,22 +862,21 @@ static VALUE re2_re2(int argc, VALUE *argv, VALUE) {
 
 /*
  * Returns a new {RE2::Regexp} object with a compiled version of
- * +pattern+ stored inside.
- *
- * @return [RE2::Regexp]
+ * `pattern` stored inside.
  *
  * @overload initialize(pattern)
  *   Returns a new {RE2::Regexp} object with a compiled version of
- *   +pattern+ stored inside with the default options.
+ *   `pattern` stored inside with the default options.
  *
  *   @param [String] pattern the pattern to compile
- *   @return [RE2::Regexp] an RE2::Regexp with the specified pattern
+ *   @return [RE2::Regexp] a {RE2::Regexp} with the specified pattern
+ *   @raise [TypeError] if the given pattern can't be coerced to a `String`
  *   @raise [NoMemoryError] if memory could not be allocated for the compiled
- *                          pattern
+ *     pattern
  *
  * @overload initialize(pattern, options)
  *   Returns a new {RE2::Regexp} object with a compiled version of
- *   +pattern+ stored inside with the specified options.
+ *   `pattern` stored inside with the specified options.
  *
  *   @param [String] pattern the pattern to compile
  *   @param [Hash] options the options with which to compile the pattern
@@ -876,12 +886,13 @@ static VALUE re2_re2(int argc, VALUE *argv, VALUE) {
  *   @option options [Boolean] :log_errors (true) log syntax and execution errors to ERROR
  *   @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)
- *   @option options [Boolean] :perl_classes (false) allow Perl's \d \s \w \D \S \W when in posix_syntax mode
- *   @option options [Boolean] :word_boundary (false) allow \b \B (word boundary and not) when in posix_syntax mode
- *   @option options [Boolean] :one_line (false) ^ and $ only match beginning and end of text when in posix_syntax mode
- *   @return [RE2::Regexp] an RE2::Regexp with the specified pattern and options
+ *   @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)
+ *   @option options [Boolean] :perl_classes (false) allow Perl's `\d` `\s` `\w` `\D` `\S` `\W` when in `posix_syntax` mode
+ *   @option options [Boolean] :word_boundary (false) allow `\b` `\B` (word boundary and not) when in `posix_syntax` mode
+ *   @option options [Boolean] :one_line (false) `^` and `$` only match beginning and end of text when in `posix_syntax` mode
+ *   @return [RE2::Regexp] a {RE2::Regexp} with the specified pattern and options
+ *   @raise [TypeError] if the given pattern can't be coerced to a `String`
  *   @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
  */
 static VALUE re2_regexp_initialize(int argc, VALUE *argv, VALUE self) {
@@ -912,16 +923,17 @@ static VALUE re2_regexp_initialize(int argc, VALUE *argv, VALUE self) {
 }
 
 /*
- * Returns a printable version of the regular expression +re2+.
+ * Returns a printable version of the regular expression.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is
+ * undefined).
  *
  * @return [String] a printable version of the regular expression
  * @example
  *   re2 = RE2::Regexp.new("woo?")
- *   re2.inspect    #=> "#<RE2::Regexp /woo?/>"
+ *   re2.inspect #=> "#<RE2::Regexp /woo?/>"
  */
 static VALUE re2_regexp_inspect(const VALUE self) {
   re2_pattern *p;
@@ -937,16 +949,16 @@ static VALUE re2_regexp_inspect(const VALUE self) {
 }
 
 /*
- * Returns a string version of the regular expression +re2+.
+ * Returns a string version of the regular expression.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is undefined).
  *
  * @return [String] a string version of the regular expression
  * @example
  *   re2 = RE2::Regexp.new("woo?")
- *   re2.to_s    #=> "woo?"
+ *   re2.to_s #=> "woo?"
  */
 static VALUE re2_regexp_to_s(const VALUE self) {
   re2_pattern *p;
@@ -958,13 +970,12 @@ static VALUE re2_regexp_to_s(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled successfully or not.
+ * Returns whether or not the regular expression was compiled successfully.
  *
  * @return [Boolean] whether or not compilation was successful
  * @example
  *   re2 = RE2::Regexp.new("woo?")
- *   re2.ok?    #=> true
+ *   re2.ok? #=> true
  */
 static VALUE re2_regexp_ok(const VALUE self) {
   re2_pattern *p;
@@ -974,13 +985,13 @@ static VALUE re2_regexp_ok(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the utf8 option set to true.
+ * Returns whether or not the regular expression was compiled with the `utf8`
+ * option set to `true`.
  *
- * @return [Boolean] the utf8 option
+ * @return [Boolean] the `utf8` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :utf8 => true)
- *   re2.utf8?    #=> true
+ *   re2 = RE2::Regexp.new("woo?", utf8: true)
+ *   re2.utf8? #=> true
  */
 static VALUE re2_regexp_utf8(const VALUE self) {
   re2_pattern *p;
@@ -990,13 +1001,13 @@ static VALUE re2_regexp_utf8(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the posix_syntax option set to true.
+ * Returns whether or not the regular expression was compiled with the
+ * `posix_syntax` option set to `true`.
  *
- * @return [Boolean] the posix_syntax option
+ * @return [Boolean] the `posix_syntax` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :posix_syntax => true)
- *   re2.posix_syntax?    #=> true
+ *   re2 = RE2::Regexp.new("woo?", posix_syntax: true)
+ *   re2.posix_syntax? #=> true
  */
 static VALUE re2_regexp_posix_syntax(const VALUE self) {
   re2_pattern *p;
@@ -1006,13 +1017,13 @@ static VALUE re2_regexp_posix_syntax(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the longest_match option set to true.
+ * Returns whether or not the regular expression was compiled with the
+ * `longest_match` option set to `true`.
  *
- * @return [Boolean] the longest_match option
+ * @return [Boolean] the `longest_match` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :longest_match => true)
- *   re2.longest_match?    #=> true
+ *   re2 = RE2::Regexp.new("woo?", longest_match: true)
+ *   re2.longest_match? #=> true
  */
 static VALUE re2_regexp_longest_match(const VALUE self) {
   re2_pattern *p;
@@ -1022,13 +1033,13 @@ static VALUE re2_regexp_longest_match(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the log_errors option set to true.
+ * Returns whether or not the regular expression was compiled with the
+ * `log_errors` option set to `true`.
  *
- * @return [Boolean] the log_errors option
+ * @return [Boolean] the `log_errors` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :log_errors => true)
- *   re2.log_errors?    #=> true
+ *   re2 = RE2::Regexp.new("woo?", log_errors: true)
+ *   re2.log_errors? #=> true
  */
 static VALUE re2_regexp_log_errors(const VALUE self) {
   re2_pattern *p;
@@ -1038,13 +1049,12 @@ static VALUE re2_regexp_log_errors(const VALUE self) {
 }
 
 /*
- * Returns the max_mem setting for the regular expression
- * +re2+.
+ * Returns the `max_mem` setting for the regular expression.
  *
- * @return [Integer] the max_mem option
+ * @return [Integer] the `max_mem` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :max_mem => 1024)
- *   re2.max_mem    #=> 1024
+ *   re2 = RE2::Regexp.new("woo?", max_mem: 1024)
+ *   re2.max_mem #=> 1024
  */
 static VALUE re2_regexp_max_mem(const VALUE self) {
   re2_pattern *p;
@@ -1054,13 +1064,13 @@ static VALUE re2_regexp_max_mem(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the literal option set to true.
+ * Returns whether or not the regular expression was compiled with the
+ * `literal` option set to `true`.
  *
- * @return [Boolean] the literal option
+ * @return [Boolean] the `literal` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :literal => true)
- *   re2.literal?    #=> true
+ *   re2 = RE2::Regexp.new("woo?", literal: true)
+ *   re2.literal? #=> true
  */
 static VALUE re2_regexp_literal(const VALUE self) {
   re2_pattern *p;
@@ -1070,13 +1080,13 @@ static VALUE re2_regexp_literal(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the never_nl option set to true.
+ * Returns whether or not the regular expression was compiled with the
+ * `never_nl` option set to `true`.
  *
- * @return [Boolean] the never_nl option
+ * @return [Boolean] the `never_nl` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :never_nl => true)
- *   re2.never_nl?    #=> true
+ *   re2 = RE2::Regexp.new("woo?", never_nl: true)
+ *   re2.never_nl? #=> true
  */
 static VALUE re2_regexp_never_nl(const VALUE self) {
   re2_pattern *p;
@@ -1086,13 +1096,13 @@ static VALUE re2_regexp_never_nl(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the case_sensitive option set to true.
+ * Returns whether or not the regular expression was compiled with the
+ * `case_sensitive` option set to `true`.
  *
- * @return [Boolean] the case_sensitive option
+ * @return [Boolean] the `case_sensitive` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :case_sensitive => true)
- *   re2.case_sensitive?    #=> true
+ *   re2 = RE2::Regexp.new("woo?", case_sensitive: true)
+ *   re2.case_sensitive? #=> true
  */
 static VALUE re2_regexp_case_sensitive(const VALUE self) {
   re2_pattern *p;
@@ -1102,27 +1112,27 @@ static VALUE re2_regexp_case_sensitive(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the case_sensitive option set to false.
+ * Returns whether or not the regular expression was compiled with the
+ * `case_sensitive` option set to `false`.
  *
- * @return [Boolean] the inverse of the case_sensitive option
+ * @return [Boolean] the inverse of the `case_sensitive` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :case_sensitive => true)
- *   re2.case_insensitive?    #=> false
- *   re2.casefold?    #=> false
+ *   re2 = RE2::Regexp.new("woo?", case_sensitive: true)
+ *   re2.case_insensitive? #=> false
+ *   re2.casefold?         #=> false
  */
 static VALUE re2_regexp_case_insensitive(const VALUE self) {
   return BOOL2RUBY(re2_regexp_case_sensitive(self) != Qtrue);
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the perl_classes option set to true.
+ * Returns whether or not the regular expression was compiled with the
+ * perl_classes option set to `true`.
  *
- * @return [Boolean] the perl_classes option
+ * @return [Boolean] the `perl_classes` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :perl_classes => true)
- *   re2.perl_classes?    #=> true
+ *   re2 = RE2::Regexp.new("woo?", perl_classes: true)
+ *   re2.perl_classes? #=> true
  */
 static VALUE re2_regexp_perl_classes(const VALUE self) {
   re2_pattern *p;
@@ -1132,13 +1142,13 @@ static VALUE re2_regexp_perl_classes(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the word_boundary option set to true.
+ * Returns whether or not the regular expression was compiled with the
+ * `word_boundary` option set to `true`.
  *
- * @return [Boolean] the word_boundary option
+ * @return [Boolean] the `word_boundary` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :word_boundary => true)
- *   re2.word_boundary?    #=> true
+ *   re2 = RE2::Regexp.new("woo?", word_boundary: true)
+ *   re2.word_boundary? #=> true
  */
 static VALUE re2_regexp_word_boundary(const VALUE self) {
   re2_pattern *p;
@@ -1148,13 +1158,13 @@ static VALUE re2_regexp_word_boundary(const VALUE self) {
 }
 
 /*
- * Returns whether or not the regular expression +re2+
- * was compiled with the one_line option set to true.
+ * Returns whether or not the regular expression was compiled with the
+ * `one_line` option set to `true`.
  *
- * @return [Boolean] the one_line option
+ * @return [Boolean] the `one_line` option
  * @example
- *   re2 = RE2::Regexp.new("woo?", :one_line => true)
- *   re2.one_line?    #=> true
+ *   re2 = RE2::Regexp.new("woo?", one_line: true)
+ *   re2.one_line? #=> true
  */
 static VALUE re2_regexp_one_line(const VALUE self) {
   re2_pattern *p;
@@ -1164,10 +1174,10 @@ static VALUE re2_regexp_one_line(const VALUE self) {
 }
 
 /*
- * If the RE2 could not be created properly, returns an
- * error string otherwise returns nil.
+ * If the {RE2::Regexp} could not be created properly, returns an error string
+ * otherwise returns `nil`.
  *
- * @return [String, nil] the error string or nil
+ * @return [String, nil] the error string or `nil`
  */
 static VALUE re2_regexp_error(const VALUE self) {
   re2_pattern *p;
@@ -1181,14 +1191,14 @@ static VALUE re2_regexp_error(const VALUE self) {
 }
 
 /*
- * If the RE2 could not be created properly, returns
- * the offending portion of the regexp otherwise returns nil.
+ * If the {RE2::Regexp} could not be created properly, returns
+ * the offending portion of the regexp otherwise returns `nil`.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is undefined).
  *
- * @return [String, nil] the offending portion of the regexp or nil
+ * @return [String, nil] the offending portion of the regexp or `nil`
  */
 static VALUE re2_regexp_error_arg(const VALUE self) {
   re2_pattern *p;
@@ -1218,8 +1228,7 @@ static VALUE re2_regexp_program_size(const VALUE self) {
 }
 
 /*
- * Returns a hash of the options currently set for
- * +re2+.
+ * Returns a hash of the options currently set for the {RE2::Regexp}.
  *
  * @return [Hash] the options
  */
@@ -1270,8 +1279,8 @@ static VALUE re2_regexp_options(const VALUE self) {
 
 /*
  * Returns the number of capturing subpatterns, or -1 if the regexp
- * wasn't valid on construction. The overall match ($0) does not
- * count: if the regexp is "(a)(b)", returns 2.
+ * wasn't valid on construction. The overall match (`$0`) does not
+ * count: if the regexp is `"(a)(b)"`, returns 2.
  *
  * @return [Integer] the number of capturing subpatterns
  */
@@ -1286,8 +1295,8 @@ static VALUE re2_regexp_number_of_capturing_groups(const VALUE self) {
  * Returns a hash of names to capturing indices of groups.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is undefined).
  *
  * @return [Hash] a hash of names to capturing indices
  */
@@ -1309,63 +1318,93 @@ static VALUE re2_regexp_named_capturing_groups(const VALUE self) {
 }
 
 /*
- * Match the pattern against the given +text+ and return either
- * a boolean (if no submatches are required) or a {RE2::MatchData}
- * instance.
+ * General matching: match the pattern against the given `text` using
+ * {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/re2.h#L562-L588
+ * `Match`} and return a {RE2::MatchData} instance with the specified number of
+ * submatches (defaults to the total number of capturing groups) or a boolean
+ * (if no submatches are required).
  *
- * @return [Boolean, RE2::MatchData]
+ * The number of submatches has a significant impact on performance: requesting
+ * one submatch is much faster than requesting more than one and requesting
+ * zero submatches is faster still.
  *
  * @overload match(text)
- *   Returns an {RE2::MatchData} containing the matching pattern and all
- *   subpatterns resulting from looking for the regexp in +text+ if the pattern
+ *   Returns a {RE2::MatchData} containing the matching pattern and all
+ *   submatches resulting from looking for the regexp in `text` if the pattern
  *   contains capturing groups.
  *
- *   Returns either true or false indicating whether a successful match was
+ *   Returns either `true` or `false` indicating whether a successful match was
  *   made if the pattern contains no capturing groups.
  *
  *   @param [String] text the text to search
- *   @return [RE2::MatchData] if the pattern contains capturing groups
+ *   @return [RE2::MatchData, nil] if the pattern contains capturing groups
  *   @return [Boolean] if the pattern does not contain capturing groups
- *   @raise [NoMemoryError] if there was not enough memory to allocate the matches
+ *   @raise [NoMemoryError] if there was not enough memory to allocate the submatches
+ *   @raise [TypeError] if given text that cannot be coerced to a `String`
  *   @example Matching with capturing groups
  *     r = RE2::Regexp.new('w(o)(o)')
- *     r.match('woo')    #=> #<RE2::MatchData "woo" 1:"o" 2:"o">
+ *     r.match('woo') #=> #<RE2::MatchData "woo" 1:"o" 2:"o">
  *   @example Matching without capturing groups
  *     r = RE2::Regexp.new('woo')
- *     r.match('woo')    #=> true
+ *     r.match('woo') #=> true
  *
- * @overload match(text, 0)
- *   Returns either true or false indicating whether a
- *   successful match was made.
+ * @overload match(text, options)
+ *   See `match(text)` but with customisable offsets for starting and ending
+ *   matches, optional anchoring to the start or both ends of the text and a
+ *   specific number of submatches to extract (padded with `nil`s if
+ *   necessary).
  *
  *   @param [String] text the text to search
- *   @return [Boolean] whether the match was successful
+ *   @param [Hash] options the options with which to perform the match
+ *   @option options [Integer] :startpos (0) offset at which to start matching
+ *   @option options [Integer] :endpos offset at which to stop matching, defaults to the text length
+ *   @option options [Symbol] :anchor (:unanchored) one of :unanchored, :anchor_start, :anchor_both to anchor the match
+ *   @option options [Integer] :submatches how many submatches to extract (0 is
+ *     fastest), defaults to the number of capturing groups
+ *   @return [RE2::MatchData, nil] if extracting any submatches
+ *   @return [Boolean] if not extracting any submatches
+ *   @raise [ArgumentError] if given a negative number of submatches, invalid
+ *     anchor or invalid startpos, endpos pair
  *   @raise [NoMemoryError] if there was not enough memory to allocate the matches
- *   @example
+ *   @raise [TypeError] if given non-String text, non-numeric number of
+ *     submatches, non-symbol anchor or non-hash options
+ *   @raise [RE2::Regexp::UnsupportedError] if given an endpos argument on a
+ *     version of RE2 that does not support it
+ *   @example Matching with capturing groups
  *     r = RE2::Regexp.new('w(o)(o)')
- *     r.match('woo', 0) #=> true
- *     r.match('bob', 0) #=> false
+ *     r.match('woo', submatches: 1) #=> #<RE2::MatchData "woo" 1:"o">
+ *     r.match('woo', submatches: 3) #=> #<RE2::MatchData "woo" 1:"o" 2:"o" 3:nil>
+ *     r.match('woot', anchor: :anchor_both, submatches: 0)
+ *     #=> false
+ *     r.match('woot', anchor: :anchor_start, submatches: 0)
+ *     #=> true
+ *   @example Matching without capturing groups
+ *     r = RE2::Regexp.new('wo+')
+ *     r.match('woot', anchor: :anchor_both)  #=> false
+ *     r.match('woot', anchor: :anchor_start) #=> true
  *
- * @overload match(text, number_of_matches)
- *   See +match(text)+ but with a specific number of
- *   matches returned (padded with nils if necessary).
+ * @overload match(text, submatches)
+ *   @deprecated Legacy syntax for matching against `text` with a specific
+ *     number of submatches to extract. Use `match(text, submatches: n)` instead.
  *
  *   @param [String] text the text to search
- *   @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
+ *   @param [Integer] submatches the number of submatches to extract
+ *   @return [RE2::MatchData, nil] if extracting any submatches
+ *   @return [Boolean] if not extracting any submatches
+ *   @raise [NoMemoryError] if there was not enough memory to allocate the submatches
+ *   @raise [TypeError] if given non-numeric number of submatches
  *   @example
  *     r = RE2::Regexp.new('w(o)(o)')
+ *     r.match('woo', 0) #=> true
  *     r.match('woo', 1) #=> #<RE2::MatchData "woo" 1:"o">
- *     r.match('woo', 3) #=> #<RE2::MatchData "woo" 1:"o" 2:"o" 3:nil>
+ *     r.match('woo', 2) #=> #<RE2::MatchData "woo" 1:"o" 2:"o">
  */
 static VALUE re2_regexp_match(int argc, VALUE *argv, const VALUE self) {
   re2_pattern *p;
   re2_matchdata *m;
-  VALUE text, number_of_matches;
+  VALUE text, options;
 
-  rb_scan_args(argc, argv, "11", &text, &number_of_matches);
+  rb_scan_args(argc, argv, "11", &text, &options);
 
   /* Ensure text is a string. */
   StringValue(text);
@@ -1373,12 +1412,80 @@ static VALUE re2_regexp_match(int argc, VALUE *argv, const VALUE self) {
   TypedData_Get_Struct(self, re2_pattern, &re2_regexp_data_type, p);
 
   int n;
+  int startpos = 0;
+  int endpos = RSTRING_LEN(text);
+  RE2::Anchor anchor = RE2::UNANCHORED;
 
-  if (RTEST(number_of_matches)) {
-    n = NUM2INT(number_of_matches);
+  if (RTEST(options)) {
+    if (FIXNUM_P(options)) {
+      n = NUM2INT(options);
+
+      if (n < 0) {
+        rb_raise(rb_eArgError, "number of matches should be >= 0");
+      }
+    } else {
+      if (TYPE(options) != T_HASH) {
+        options = rb_Hash(options);
+      }
 
-    if (n < 0) {
-      rb_raise(rb_eArgError, "number of matches should be >= 0");
+      VALUE endpos_option = rb_hash_aref(options, ID2SYM(id_endpos));
+      if (!NIL_P(endpos_option)) {
+#ifdef HAVE_ENDPOS_ARGUMENT
+        Check_Type(endpos_option, T_FIXNUM);
+
+        endpos = NUM2INT(endpos_option);
+
+        if (endpos < 0) {
+          rb_raise(rb_eArgError, "endpos should be >= 0");
+        }
+#else
+        rb_raise(re2_eRegexpUnsupportedError, "current version of RE2::Match() does not support endpos argument");
+#endif
+      }
+
+      VALUE anchor_option = rb_hash_aref(options, ID2SYM(id_anchor));
+      if (!NIL_P(anchor_option)) {
+        Check_Type(anchor_option, T_SYMBOL);
+
+        ID id_anchor_option = SYM2ID(anchor_option);
+        if (id_anchor_option == id_unanchored) {
+          anchor = RE2::UNANCHORED;
+        } else if (id_anchor_option == id_anchor_start) {
+          anchor = RE2::ANCHOR_START;
+        } else if (id_anchor_option == id_anchor_both) {
+          anchor = RE2::ANCHOR_BOTH;
+        } else {
+          rb_raise(rb_eArgError, "anchor should be one of: :unanchored, :anchor_start, :anchor_both");
+        }
+      }
+
+      VALUE submatches_option = rb_hash_aref(options, ID2SYM(id_submatches));
+      if (!NIL_P(submatches_option)) {
+        Check_Type(submatches_option, T_FIXNUM);
+
+        n = NUM2INT(submatches_option);
+
+        if (n < 0) {
+          rb_raise(rb_eArgError, "number of matches should be >= 0");
+        }
+      } else {
+        if (!p->pattern->ok()) {
+          return Qnil;
+        }
+
+        n = p->pattern->NumberOfCapturingGroups();
+      }
+
+      VALUE startpos_option = rb_hash_aref(options, ID2SYM(id_startpos));
+      if (!NIL_P(startpos_option)) {
+        Check_Type(startpos_option, T_FIXNUM);
+
+        startpos = NUM2INT(startpos_option);
+
+        if (startpos < 0) {
+          rb_raise(rb_eArgError, "startpos should be >= 0");
+        }
+      }
     }
   } else {
     if (!p->pattern->ok()) {
@@ -1388,12 +1495,16 @@ static VALUE re2_regexp_match(int argc, VALUE *argv, const VALUE self) {
     n = p->pattern->NumberOfCapturingGroups();
   }
 
+  if (startpos > endpos) {
+    rb_raise(rb_eArgError, "startpos should be <= endpos");
+  }
+
   if (n == 0) {
 #ifdef HAVE_ENDPOS_ARGUMENT
-    bool matched = p->pattern->Match(RSTRING_PTR(text), 0,
-        RSTRING_LEN(text), RE2::UNANCHORED, 0, 0);
+    bool matched = p->pattern->Match(RSTRING_PTR(text), startpos,
+        endpos, anchor, 0, 0);
 #else
-    bool matched = p->pattern->Match(RSTRING_PTR(text), 0, RE2::UNANCHORED,
+    bool matched = p->pattern->Match(RSTRING_PTR(text), startpos, anchor,
         0, 0);
 #endif
     return BOOL2RUBY(matched);
@@ -1418,11 +1529,11 @@ static VALUE re2_regexp_match(int argc, VALUE *argv, const VALUE self) {
     m->number_of_matches = n;
 
 #ifdef HAVE_ENDPOS_ARGUMENT
-    bool matched = p->pattern->Match(RSTRING_PTR(m->text), 0,
-        RSTRING_LEN(m->text), RE2::UNANCHORED, m->matches, n);
+    bool matched = p->pattern->Match(RSTRING_PTR(m->text), startpos,
+        endpos, anchor, m->matches, n);
 #else
-    bool matched = p->pattern->Match(RSTRING_PTR(m->text), 0,
-        RE2::UNANCHORED, m->matches, n);
+    bool matched = p->pattern->Match(RSTRING_PTR(m->text), startpos,
+        anchor, m->matches, n);
 #endif
     if (matched) {
       return matchdata;
@@ -1433,22 +1544,54 @@ static VALUE re2_regexp_match(int argc, VALUE *argv, const VALUE self) {
 }
 
 /*
- * Returns true or false to indicate a successful match.
- * Equivalent to +re2.match(text, 0)+.
+ * Returns true if the pattern matches any substring of the given text using
+ * {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/re2.h#L413-L427
+ * `PartialMatch`}.
  *
  * @return [Boolean] whether the match was successful
+ * @raise [TypeError] if text cannot be coerced to a `String`
  */
 static VALUE re2_regexp_match_p(const VALUE self, VALUE text) {
-  VALUE argv[2] = { text, INT2FIX(0) };
+  re2_pattern *p;
+
+  /* Ensure text is a string. */
+  StringValue(text);
+
+  TypedData_Get_Struct(self, re2_pattern, &re2_regexp_data_type, p);
+
+  return BOOL2RUBY(RE2::PartialMatch(RSTRING_PTR(text), *p->pattern));
+}
+
+/*
+ * Returns true if the pattern matches the given text using
+ * {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/re2.h#L376-L411
+ * `FullMatch`}.
+ *
+ * @return [Boolean] whether the match was successful
+ * @raise [TypeError] if text cannot be coerced to a `String`
+ */
+static VALUE re2_regexp_full_match_p(const VALUE self, VALUE text) {
+  re2_pattern *p;
+
+  /* Ensure text is a string. */
+  StringValue(text);
 
-  return re2_regexp_match(2, argv, self);
+  TypedData_Get_Struct(self, re2_pattern, &re2_regexp_data_type, p);
+
+  return BOOL2RUBY(RE2::FullMatch(RSTRING_PTR(text), *p->pattern));
 }
 
 /*
- * Returns a {RE2::Scanner} for scanning the given text incrementally.
+ * Returns a {RE2::Scanner} for scanning the given text incrementally with
+ * {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/re2.h#L447-L463
+ * `FindAndConsume`}.
  *
+ * @param [text] text the text to scan incrementally
+ * @return [RE2::Scanner] an `Enumerable` {RE2::Scanner} object
+ * @raise [TypeError] if `text` cannot be coerced to a `String`
  * @example
  *   c = RE2::Regexp.new('(\w+)').scan("Foo bar baz")
+ *   #=> #<RE2::Scanner:0x0000000000000001>
  */
 static VALUE re2_regexp_scan(const VALUE self, VALUE text) {
   /* Ensure text is a string. */
@@ -1477,17 +1620,40 @@ static VALUE re2_regexp_scan(const VALUE self, VALUE text) {
 }
 
 /*
- * Returns a copy of +str+ with the first occurrence +pattern+
- * replaced with +rewrite+.
+ * Returns whether the underlying RE2 version supports passing an `endpos`
+ * argument to
+ * {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/re2.h#L562-L588
+ * Match}. If not, {RE2::Regexp#match} will raise an error if attempting to
+ * pass an `endpos`.
+ *
+ * @return [Boolean] whether the underlying
+ *   {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/re2.h#L562-L588
+ *   Match} has an endpos argument
+ */
+static VALUE re2_regexp_match_has_endpos_argument_p(VALUE) {
+#ifdef HAVE_ENDPOS_ARGUMENT
+  return Qtrue;
+#else
+  return Qfalse;
+#endif
+}
+
+/*
+ * Returns a copy of `str` with the first occurrence `pattern` replaced with
+ * `rewrite` using
+ * {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/re2.h#L465-L480
+ * `Replace`}.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is undefined).
  *
  * @param [String] str the string to modify
  * @param [String, RE2::Regexp] pattern a regexp matching text to be replaced
  * @param [String] rewrite the string to replace with
  * @return [String] the resulting string
+ * @raise [TypeError] if the given rewrite or pattern (if not provided as a
+ *   {RE2::Regexp}) cannot be coerced to `String`s
  * @example
  *   RE2.Replace("hello there", "hello", "howdy") #=> "howdy there"
  *   re2 = RE2::Regexp.new("hel+o")
@@ -1523,20 +1689,24 @@ static VALUE re2_Replace(VALUE, VALUE str, VALUE pattern,
 }
 
 /*
- * Return a copy of +str+ with +pattern+ replaced by +rewrite+.
+ * Return a copy of `str` with `pattern` replaced by `rewrite` using
+ * {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/re2.h#L482-L497
+ * `GlobalReplace`}.
  *
  * Note RE2 only supports UTF-8 and ISO-8859-1 encoding so strings will be
- * returned in UTF-8 by default or ISO-8859-1 if the :utf8 option for the
- * RE2::Regexp is set to false (any other encoding's behaviour is undefined).
+ * returned in UTF-8 by default or ISO-8859-1 if the `:utf8` option for the
+ * {RE2::Regexp} is set to `false` (any other encoding's behaviour is undefined).
  *
  * @param [String] str the string to modify
  * @param [String, RE2::Regexp] pattern a regexp matching text to be replaced
  * @param [String] rewrite the string to replace with
+ * @raise [TypeError] if the given rewrite or pattern (if not provided as a
+ *   {RE2::Regexp}) cannot be coerced to `String`s
  * @return [String] the resulting string
  * @example
  *   re2 = RE2::Regexp.new("oo?")
- *   RE2.GlobalReplace("whoops-doops", re2, "e")  #=> "wheps-deps"
- *   RE2.GlobalReplace("hello there", "e", "i")   #=> "hillo thiri"
+ *   RE2.GlobalReplace("whoops-doops", re2, "e") #=> "wheps-deps"
+ *   RE2.GlobalReplace("hello there", "e", "i")  #=> "hillo thiri"
  */
 static VALUE re2_GlobalReplace(VALUE, VALUE str, VALUE pattern,
                                VALUE rewrite) {
@@ -1568,14 +1738,17 @@ static VALUE re2_GlobalReplace(VALUE, VALUE str, VALUE pattern,
 }
 
 /*
- * Returns a version of str with all potentially meaningful regexp
- * characters escaped. The returned string, used as a regular
- * expression, will exactly match the original string.
+ * Returns a version of `str` with all potentially meaningful regexp characters
+ * escaped using
+ * {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/re2.h#L512-L518
+ * `QuoteMeta`}. The returned string, used as a regular expression, will
+ * exactly match the original string.
  *
  * @param [String] unquoted the unquoted string
+ * @raise [TypeError] if the given unquoted string cannot be coerced to a `String`
  * @return [String] the escaped string
  * @example
- *   RE2::Regexp.escape("1.5-2.0?")    #=> "1\.5\-2\.0\?"
+ *   RE2::Regexp.escape("1.5-2.0?") #=> "1\.5\-2\.0\?"
  */
 static VALUE re2_QuoteMeta(VALUE, VALUE unquoted) {
   StringValue(unquoted);
@@ -1641,14 +1814,14 @@ static VALUE re2_set_allocate(VALUE klass) {
  *   Returns a new {RE2::Set} object for the specified anchor with the default
  *   options.
  *
- *   @param [Symbol] anchor One of :unanchored, :anchor_start, :anchor_both
- *   @raise [ArgumentError] if anchor is not :unanchored, :anchor_start or :anchor_both
+ *   @param [Symbol] anchor one of `:unanchored`, `:anchor_start`, `:anchor_both`
+ *   @raise [ArgumentError] if anchor is not `:unanchored`, `:anchor_start` or `:anchor_both`
  *   @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
  *
  * @overload initialize(anchor, options)
  *   Returns a new {RE2::Set} object with the specified options.
  *
- *   @param [Symbol] anchor One of :unanchored, :anchor_start, :anchor_both
+ *   @param [Symbol] anchor one of `:unanchored`, `:anchor_start`, `:anchor_both`
  *   @param [Hash] options the options with which to compile the pattern
  *   @option options [Boolean] :utf8 (true) text and pattern are UTF-8; otherwise Latin-1
  *   @option options [Boolean] :posix_syntax (false) restrict regexps to POSIX egrep syntax
@@ -1656,13 +1829,13 @@ static VALUE re2_set_allocate(VALUE klass) {
  *   @option options [Boolean] :log_errors (true) log syntax and execution errors to ERROR
  *   @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)
- *   @option options [Boolean] :perl_classes (false) allow Perl's \d \s \w \D \S \W when in posix_syntax mode
- *   @option options [Boolean] :word_boundary (false) allow \b \B (word boundary and not) when in posix_syntax mode
- *   @option options [Boolean] :one_line (false) ^ and $ only match beginning and end of text when in posix_syntax mode
- *   @return [RE2::Set] an RE2::Set with the specified anchor and options
- *   @raise [ArgumentError] if anchor is not one of the accepted choices
+ *   @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)
+ *   @option options [Boolean] :perl_classes (false) allow Perl's `\d` `\s` `\w` `\D` `\S` `\W` when in `posix_syntax` mode
+ *   @option options [Boolean] :word_boundary (false) allow `\b` `\B` (word boundary and not) when in `posix_syntax` mode
+ *   @option options [Boolean] :one_line (false) `^` and `$` only match beginning and end of text when in `posix_syntax` mode
+ *   @return [RE2::Set] a {RE2::Set} with the specified anchor and options
+ *   @raise [ArgumentError] if `anchor` is not one of the accepted choices
  *   @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
  */
 static VALUE re2_set_initialize(int argc, VALUE *argv, VALUE self) {
@@ -1676,12 +1849,12 @@ static VALUE re2_set_initialize(int argc, VALUE *argv, VALUE self) {
 
   if (!NIL_P(anchor)) {
     Check_Type(anchor, T_SYMBOL);
-    ID id_anchor = SYM2ID(anchor);
-    if (id_anchor == id_unanchored) {
+    ID id_anchor_arg = SYM2ID(anchor);
+    if (id_anchor_arg == id_unanchored) {
       re2_anchor = RE2::UNANCHORED;
-    } else if (id_anchor == id_anchor_start) {
+    } else if (id_anchor_arg == id_anchor_start) {
       re2_anchor = RE2::ANCHOR_START;
-    } else if (id_anchor == id_anchor_both) {
+    } else if (id_anchor_arg == id_anchor_both) {
       re2_anchor = RE2::ANCHOR_BOTH;
     } else {
       rb_raise(rb_eArgError, "anchor should be one of: :unanchored, :anchor_start, :anchor_both");
@@ -1704,15 +1877,16 @@ static VALUE re2_set_initialize(int argc, VALUE *argv, VALUE self) {
 
 /*
  * Adds a pattern to the set. Returns the index that will identify the pattern
- * in the output of #match. Cannot be called after #compile has been called.
+ * in the output of {RE2::Set#match}. Cannot be called after {RE2::Set#compile}
+ * has been called.
  *
  * @param [String] pattern the regex pattern
  * @return [Integer] the index of the pattern in the set
  * @raise [ArgumentError] if called after compile or the pattern is rejected
  * @example
  *   set = RE2::Set.new
- *   set.add("abc")    #=> 0
- *   set.add("def")    #=> 1
+ *   set.add("abc") #=> 0
+ *   set.add("def") #=> 1
  */
 static VALUE re2_set_add(VALUE self, VALUE pattern) {
   StringValue(pattern);
@@ -1740,14 +1914,14 @@ static VALUE re2_set_add(VALUE self, VALUE pattern) {
 }
 
 /*
- * Compiles a Set so it can be used to match against. Must be called after #add
- * and before #match.
+ * Compiles a {RE2::Set} so it can be used to match against. Must be called
+ * after {RE2::Set#add} and before {RE2::Set#match}.
  *
- * @return [Bool] whether compilation was a success
+ * @return [Boolean] whether compilation was a success
  * @example
  *   set = RE2::Set.new
  *   set.add("abc")
- *   set.compile    # => true
+ *   set.compile #=> true
  */
 static VALUE re2_set_compile(VALUE self) {
   re2_set *s;
@@ -1757,11 +1931,12 @@ static VALUE re2_set_compile(VALUE self) {
 }
 
 /*
- * Returns whether the underlying re2 version outputs error information from
- * RE2::Set::Match. If not, #match will raise an error if attempting to set its
- * :exception option to true.
+ * Returns whether the underlying RE2 version outputs error information from
+ * {https://github.com/google/re2/blob/bc0faab533e2b27b85b8ad312abf061e33ed6b5d/re2/set.h#L62-L65
+ * `RE2::Set::Match`}. If not, {RE2::Set#match} will raise an error if attempting to set
+ * its `:exception` option to `true`.
  *
- * @return [Bool] whether the underlying re2 outputs error information from Set matches
+ * @return [Boolean] whether the underlying RE2 outputs error information from {RE2::Set} matches
  */
 static VALUE re2_set_match_raises_errors_p(VALUE) {
 #ifdef HAVE_ERROR_INFO_ARGUMENT
@@ -1785,31 +1960,31 @@ static VALUE re2_set_match_raises_errors_p(VALUE) {
  *   @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
+ *   @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]
+ *     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.
+ *   `: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)
+ *   @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
+ *   @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]
+ *     set.match("abcdef", exception: true) #=> [0, 1]
  */
 static VALUE re2_set_match(int argc, VALUE *argv, const VALUE self) {
   VALUE str, options;
@@ -1877,6 +2052,8 @@ static VALUE re2_set_match(int argc, VALUE *argv, const VALUE self) {
 extern "C" void Init_re2(void) {
   re2_mRE2 = rb_define_module("RE2");
   re2_cRegexp = rb_define_class_under(re2_mRE2, "Regexp", rb_cObject);
+  re2_eRegexpUnsupportedError = rb_define_class_under(re2_cRegexp,
+      "UnsupportedError", rb_const_get(rb_cObject, rb_intern("StandardError")));
   re2_cMatchData = rb_define_class_under(re2_mRE2, "MatchData", rb_cObject);
   re2_cScanner = rb_define_class_under(re2_mRE2, "Scanner", rb_cObject);
   re2_cSet = rb_define_class_under(re2_mRE2, "Set", rb_cObject);
@@ -1930,6 +2107,8 @@ extern "C" void Init_re2(void) {
   rb_define_method(re2_cScanner, "rewind",
       RUBY_METHOD_FUNC(re2_scanner_rewind), 0);
 
+  rb_define_singleton_method(re2_cRegexp, "match_has_endpos_argument?",
+      RUBY_METHOD_FUNC(re2_regexp_match_has_endpos_argument_p), 0);
   rb_define_method(re2_cRegexp, "initialize",
       RUBY_METHOD_FUNC(re2_regexp_initialize), -1);
   rb_define_method(re2_cRegexp, "ok?", RUBY_METHOD_FUNC(re2_regexp_ok), 0);
@@ -1947,12 +2126,14 @@ extern "C" void Init_re2(void) {
       RUBY_METHOD_FUNC(re2_regexp_named_capturing_groups), 0);
   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_p), 1);
-  rb_define_method(re2_cRegexp, "=~",
-      RUBY_METHOD_FUNC(re2_regexp_match_p), 1);
-  rb_define_method(re2_cRegexp, "===",
+  rb_define_method(re2_cRegexp, "match?", RUBY_METHOD_FUNC(re2_regexp_match_p),
+      1);
+  rb_define_method(re2_cRegexp, "partial_match?",
       RUBY_METHOD_FUNC(re2_regexp_match_p), 1);
+  rb_define_method(re2_cRegexp, "=~", RUBY_METHOD_FUNC(re2_regexp_match_p), 1);
+  rb_define_method(re2_cRegexp, "===", RUBY_METHOD_FUNC(re2_regexp_match_p), 1);
+  rb_define_method(re2_cRegexp, "full_match?",
+      RUBY_METHOD_FUNC(re2_regexp_full_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);
@@ -2009,6 +2190,8 @@ extern "C" void Init_re2(void) {
       RUBY_METHOD_FUNC(re2_QuoteMeta), 1);
   rb_define_singleton_method(re2_cRegexp, "quote",
       RUBY_METHOD_FUNC(re2_QuoteMeta), 1);
+
+  // (see RE2::Regexp#initialize)
   rb_define_singleton_method(re2_cRegexp, "compile",
       RUBY_METHOD_FUNC(rb_class_new_instance), -1);
 
@@ -2027,7 +2210,11 @@ extern "C" void Init_re2(void) {
   id_word_boundary = rb_intern("word_boundary");
   id_one_line = rb_intern("one_line");
   id_unanchored = rb_intern("unanchored");
+  id_anchor = rb_intern("anchor");
   id_anchor_start = rb_intern("anchor_start");
   id_anchor_both = rb_intern("anchor_both");
   id_exception = rb_intern("exception");
+  id_submatches = rb_intern("submatches");
+  id_startpos = rb_intern("startpos");
+  id_endpos = rb_intern("endpos");
 }