Class: RE2::MatchData

Inherits:
Object show all
Defined in:
ext/re2/re2.cc

Instance Method Summary collapse

Instance Method Details

#[](index) ⇒ String? #[](start, length) ⇒ Array<String, nil> #[](range) ⇒ Array<String, nil> #[](name) ⇒ String?

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).

Overloads:

  • #[](index) ⇒ String?

    Access a particular match by index.

    Examples:

    m = RE2::Regexp.new('(\d+)').match("bob 123")
m[0]    #=> "123"

    Parameters:

    • index (Integer) —

      the index of the match to fetch

    Returns:

    • (String, nil) —

      the specified match

  • #[](start, length) ⇒ Array<String, nil>

    Access a range of matches by starting index and length.

    Examples:

    m = RE2::Regexp.new('(\d+)').match("bob 123")
m[0, 1]    #=> ["123"]

    Parameters:

    • start (Integer) —

      the index from which to start

    • length (Integer) —

      the number of elements to fetch

    Returns:

    • (Array<String, nil>) —

      the specified matches

  • #[](range) ⇒ Array<String, nil>

    Access a range of matches by index.

    Examples:

    m = RE2::Regexp.new('(\d+)').match("bob 123")
m[0..1]    #=> "[123", "123"]

    Parameters:

    • range (Range) —

      the range of match indexes to fetch

    Returns:

    • (Array<String, nil>) —

      the specified matches

  • #[](name) ⇒ String?

    Access a particular match by name.

    Examples:

    m = RE2::Regexp.new('(?P<number>\d+)').match("bob 123")
m["number"] #=> "123"
m[:number]  #=> "123"

    Parameters:

    • name (String, Symbol) —

      the name of the match to fetch

    Returns:

    • (String, nil) —

      the specific match

Returns:



665
666
667
668
669
670
671
672
673
674
675
676
677
678
 
# File 'ext/re2/re2.cc', line 665

static VALUE re2_matchdata_aref(int argc, VALUE *argv, const VALUE self) {
  VALUE idx, rest;
  rb_scan_args(argc, argv, "11", &idx, &rest);

  if (TYPE(idx) == T_STRING) {
    return re2_matchdata_named_match(RSTRING_PTR(idx), self);
  } else if (SYMBOL_P(idx)) {
    return re2_matchdata_named_match(rb_id2name(SYM2ID(idx)), self);
  } else if (!NIL_P(rest) || !FIXNUM_P(idx) || FIX2INT(idx) < 0) {
    return rb_ary_aref(argc, argv, re2_matchdata_to_a(self));
  } else {
    return re2_matchdata_nth_match(FIX2INT(idx), self);
  }
}

#begin(n) ⇒ Integer

Returns the offset of the start of the nth element of the matchdata.

Examples:

m = RE2::Regexp.new('ob (\d+)').match("bob 123")
m.begin(0)  #=> 1
m.begin(1)  #=> 4

Parameters:

  • n (Integer, String, Symbol) —

    the name or number of the match

Returns:

  • (Integer) —

    the offset of the start of the match



470
471
472
473
474
475
476
477
478
479
480
481
482
483
 
# File 'ext/re2/re2.cc', line 470

static VALUE re2_matchdata_begin(const VALUE self, VALUE n) {
  re2_matchdata *m;

  TypedData_Get_Struct(self, re2_matchdata, &re2_matchdata_data_type, m);

  re2::StringPiece *match = re2_matchdata_find_match(n, self);
  if (match == NULL) {
    return Qnil;
  } else {
    long offset = match->data() - RSTRING_PTR(m->text);

    return LONG2NUM(rb_str_sublen(m->text, offset));
  }
}

#deconstruct ⇒ Array<String, nil>

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).

Examples:

m = RE2::Regexp.new('(\d+)').match("bob 123")
m.deconstruct    #=> ["123"]

pattern matching

case RE2::Regexp.new('(\d+) (\d+)').match("bob 123 456")
in x, y
  puts "Matched #{x} #{y}"
else
  puts "Unrecognised match"
end

Returns:

  • (Array<String, nil>) —

    the array of submatches



753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
 
# File 'ext/re2/re2.cc', line 753

static VALUE re2_matchdata_deconstruct(const VALUE self) {
  re2_matchdata *m;
  re2_pattern *p;

  TypedData_Get_Struct(self, re2_matchdata, &re2_matchdata_data_type, m);
  TypedData_Get_Struct(m->regexp, re2_pattern, &re2_regexp_data_type, p);

  VALUE array = rb_ary_new2(m->number_of_matches - 1);
  for (int i = 1; i < m->number_of_matches; ++i) {
    re2::StringPiece *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()));
    }
  }

  return array;
}

#deconstruct_keys(keys) ⇒ Hash

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.

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).

Examples:

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"}

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

Parameters:

  • keys (Array<Symbol>, nil) —

    an array of Symbol capturing group names or nil to return all names

Returns:

  • (Hash) —

    a hash of capturing group names to submatches



803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
 
# File 'ext/re2/re2.cc', line 803

static VALUE re2_matchdata_deconstruct_keys(const VALUE self, const VALUE keys) {
  re2_matchdata *m;
  re2_pattern *p;

  TypedData_Get_Struct(self, re2_matchdata, &re2_matchdata_data_type, m);
  TypedData_Get_Struct(m->regexp, re2_pattern, &re2_regexp_data_type, p);

  const std::map<std::string, int>& groups = p->pattern->NamedCapturingGroups();
  VALUE capturing_groups = rb_hash_new();

  if (NIL_P(keys)) {
    for (std::map<std::string, int>::const_iterator it = groups.begin(); it != groups.end(); ++it) {
      rb_hash_aset(capturing_groups,
          ID2SYM(rb_intern(it->first.data())),
          re2_matchdata_nth_match(it->second, self));
    }
  } else {
    Check_Type(keys, T_ARRAY);

    if (p->pattern->NumberOfCapturingGroups() >= RARRAY_LEN(keys)) {
      for (int i = 0; i < RARRAY_LEN(keys); ++i) {
        VALUE key = rb_ary_entry(keys, i);
        Check_Type(key, T_SYMBOL);
        const char *name = rb_id2name(SYM2ID(key));
        std::map<std::string, int>::const_iterator search = groups.find(name);

        if (search != groups.end()) {
          rb_hash_aset(capturing_groups, key, re2_matchdata_nth_match(search->second, self));
        } else {
          break;
        }
      }
    }
  }

  return capturing_groups;
}

#end(n) ⇒ Integer

Returns the offset of the character following the end of the nth element of the matchdata.

Examples:

m = RE2::Regexp.new('ob (\d+) b').match("bob 123 bob")
m.end(0)  #=> 9
m.end(1)  #=> 7

Parameters:

  • n (Integer, String, Symbol) —

    the name or number of the match

Returns:

  • (Integer) —

    the offset of the character following the end of the match



495
496
497
498
499
500
501
502
503
504
505
506
507
508
 
# File 'ext/re2/re2.cc', line 495

static VALUE re2_matchdata_end(const VALUE self, VALUE n) {
  re2_matchdata *m;

  TypedData_Get_Struct(self, re2_matchdata, &re2_matchdata_data_type, m);

  re2::StringPiece *match = re2_matchdata_find_match(n, self);
  if (match == NULL) {
    return Qnil;
  } else {
    long offset = (match->data() - RSTRING_PTR(m->text)) + match->size();

    return LONG2NUM(rb_str_sublen(m->text, offset));
  }
}

#inspect ⇒ String

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).

Examples:

m = RE2::Regexp.new('(\d+)').match("bob 123")
m.inspect    #=> "#<RE2::MatchData \"123\" 1:\"123\">"

Returns:

  • (String) —

    a printable version of the match



701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
 
# File 'ext/re2/re2.cc', line 701

static VALUE re2_matchdata_inspect(const VALUE self) {
  re2_matchdata *m;
  re2_pattern *p;

  TypedData_Get_Struct(self, re2_matchdata, &re2_matchdata_data_type, m);
  TypedData_Get_Struct(m->regexp, re2_pattern, &re2_regexp_data_type, p);

  std::ostringstream output;
  output << "#<RE2::MatchData";

  for (int i = 0; i < m->number_of_matches; ++i) {
    output << " ";

    if (i > 0) {
      output << i << ":";
    }

    VALUE match = re2_matchdata_nth_match(i, self);

    if (match == Qnil) {
      output << "nil";
    } else {
      output << "\"" << RSTRING_PTR(match) << "\"";
    }
  }

  output << ">";

  return encoded_str_new(output.str().data(), output.str().length(),
      p->pattern->options().encoding());
}

#length ⇒ Integer

Returns the number of elements in the match array (including nils).

Examples:

m = RE2::Regexp.new('(\d+)').match("bob 123")
m.size      #=> 2
m.length    #=> 2

Returns:

  • (Integer) —

    the number of elements



452
453
454
455
456
457
458
 
# File 'ext/re2/re2.cc', line 452

static VALUE re2_matchdata_size(const VALUE self) {
  re2_matchdata *m;

  TypedData_Get_Struct(self, re2_matchdata, &re2_matchdata_data_type, m);

  return INT2FIX(m->number_of_matches);
}

#regexp ⇒ RE2::Regexp

Returns the Regexp used in the match.

Examples:

m = RE2::Regexp.new('(\d+)').match("bob 123")
m.regexp    #=> #<RE2::Regexp /(\d+)/>

Returns:



518
519
520
521
522
523
 
# File 'ext/re2/re2.cc', line 518

static VALUE re2_matchdata_regexp(const VALUE self) {
  re2_matchdata *m;
  TypedData_Get_Struct(self, re2_matchdata, &re2_matchdata_data_type, m);

  return m->regexp;
}

#size ⇒ Integer

Returns the number of elements in the match array (including nils).

Examples:

m = RE2::Regexp.new('(\d+)').match("bob 123")
m.size      #=> 2
m.length    #=> 2

Returns:

  • (Integer) —

    the number of elements



452
453
454
455
456
457
458
 
# File 'ext/re2/re2.cc', line 452

static VALUE re2_matchdata_size(const VALUE self) {
  re2_matchdata *m;

  TypedData_Get_Struct(self, re2_matchdata, &re2_matchdata_data_type, m);

  return INT2FIX(m->number_of_matches);
}

#string ⇒ String

Returns a frozen copy of the string passed into match.

Examples:

m = RE2::Regexp.new('(\d+)').match("bob 123")
m.string  #=> "bob 123"

Returns:

  • (String) —

    a frozen copy of the passed string.



280
281
282
283
284
285
 
# File 'ext/re2/re2.cc', line 280

static VALUE re2_matchdata_string(const VALUE self) {
  re2_matchdata *m;
  TypedData_Get_Struct(self, re2_matchdata, &re2_matchdata_data_type, m);

  return m->text;
}

#to_a ⇒ Array<String, nil>

Returns the array of matches.

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).

Examples:

m = RE2::Regexp.new('(\d+)').match("bob 123")
m.to_a    #=> ["123", "123"]

Returns:

  • (Array<String, nil>) —

    the array of matches



558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
 
# File 'ext/re2/re2.cc', line 558

static VALUE re2_matchdata_to_a(const VALUE self) {
  re2_matchdata *m;
  re2_pattern *p;

  TypedData_Get_Struct(self, re2_matchdata, &re2_matchdata_data_type, m);
  TypedData_Get_Struct(m->regexp, re2_pattern, &re2_regexp_data_type, p);

  VALUE array = rb_ary_new2(m->number_of_matches);
  for (int i = 0; i < m->number_of_matches; ++i) {
    re2::StringPiece *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()));
    }
  }

  return array;
}

#to_s ⇒ String

Returns the entire matched string.

Returns:

  • (String) —

    the entire matched string



685
686
687
 
# File 'ext/re2/re2.cc', line 685

static VALUE re2_matchdata_to_s(const VALUE self) {
  return re2_matchdata_nth_match(0, self);
}