Class: RE2::MatchData

Inherits:
Object
  • 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.

Overloads:

  • #[](index) ⇒ String?

    Access a particular match by index.

    Examples:

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

    Parameters:

    • index (Fixnum) —

      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 (Fixnum) —

      the index from which to start

    • length (Fixnum) —

      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:



622
623
624
625
626
627
628
629
630
631
632
633
634
635
 
# File 'ext/re2/re2.cc', line 622

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

  if (TYPE(idx) == T_STRING) {
    return re2_matchdata_named_match(StringValuePtr(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) ⇒ Fixnum

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 (Fixnum, String, Symbol) —

    the name or number of the match

Returns:

  • (Fixnum) —

    the offset of the start of the match



419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
 
# File 'ext/re2/re2.cc', line 419

static VALUE re2_matchdata_begin(VALUE self, VALUE n) {
  re2_matchdata *m;
  re2_pattern *p;
  re2::StringPiece *match;
  long offset;

  Data_Get_Struct(self, re2_matchdata, m);
  Data_Get_Struct(m->regexp, re2_pattern, p);

  match = re2_matchdata_find_match(n, self);
  if (match == NULL) {
    return Qnil;
  } else {
    offset = reinterpret_cast<uintptr_t>(match->data()) - reinterpret_cast<uintptr_t>(StringValuePtr(m->text));

    return ENCODED_STR_SUBLEN(StringValue(m->text), offset,
           p->pattern->options().encoding() == RE2::Options::EncodingUTF8 ? "UTF-8" : "ISO-8859-1");
  }
}

#deconstruct ⇒ Array<String, nil>

Returns the array of submatches for pattern matching.

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



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

static VALUE re2_matchdata_deconstruct(VALUE self) {
  int i;
  re2_matchdata *m;
  re2_pattern *p;
  re2::StringPiece *match;
  VALUE array;

  Data_Get_Struct(self, re2_matchdata, m);
  Data_Get_Struct(m->regexp, re2_pattern, p);

  array = rb_ary_new2(m->number_of_matches - 1);
  for (i = 1; i < m->number_of_matches; i++) {
    match = &m->matches[i];

    if (match->empty()) {
      rb_ary_push(array, Qnil);
    } else {
      rb_ary_push(array, ENCODED_STR_NEW(match->data(), match->size(),
            p->pattern->options().encoding() == RE2::Options::EncodingUTF8 ? "UTF-8" : "ISO-8859-1"));
    }
  }

  return array;
}

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

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



755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
 
# File 'ext/re2/re2.cc', line 755

static VALUE re2_matchdata_deconstruct_keys(VALUE self, VALUE keys) {
  int i;
  VALUE capturing_groups, key;
  re2_matchdata *m;
  re2_pattern *p;
  map<string, int> groups;
  map<string, int>::iterator iterator;

  Data_Get_Struct(self, re2_matchdata, m);
  Data_Get_Struct(m->regexp, re2_pattern, p);

  groups = p->pattern->NamedCapturingGroups();
  capturing_groups = rb_hash_new();

  if (NIL_P(keys)) {
    for (iterator = groups.begin(); iterator != groups.end(); iterator++) {
      rb_hash_aset(capturing_groups,
          ID2SYM(rb_intern(iterator->first.data())),
          re2_matchdata_nth_match(iterator->second, self));
    }
  } else {
    Check_Type(keys, T_ARRAY);

    if (p->pattern->NumberOfCapturingGroups() >= RARRAY_LEN(keys)) {
      for (i = 0; i < RARRAY_LEN(keys); i++) {
        key = rb_ary_entry(keys, i);
        Check_Type(key, T_SYMBOL);
        string name(rb_id2name(SYM2ID(key)));

        if (groups.count(name) == 0) {
          break;
        }

        rb_hash_aset(capturing_groups, key, re2_matchdata_nth_match(groups[name], self));
      }
    }
  }

  return capturing_groups;
}

#end(n) ⇒ Fixnum

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 (Fixnum, String, Symbol) —

    the name or number of the match

Returns:

  • (Fixnum) —

    the offset of the character following the end of the match



449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
 
# File 'ext/re2/re2.cc', line 449

static VALUE re2_matchdata_end(VALUE self, VALUE n) {
  re2_matchdata *m;
  re2_pattern *p;
  re2::StringPiece *match;
  long offset;

  Data_Get_Struct(self, re2_matchdata, m);
  Data_Get_Struct(m->regexp, re2_pattern, p);

  match = re2_matchdata_find_match(n, self);

  if (match == NULL) {
    return Qnil;
  } else {
    offset = reinterpret_cast<uintptr_t>(match->data()) - reinterpret_cast<uintptr_t>(StringValuePtr(m->text)) + match->size();

    return ENCODED_STR_SUBLEN(StringValue(m->text), offset,
           p->pattern->options().encoding() == RE2::Options::EncodingUTF8 ? "UTF-8" : "ISO-8859-1");
  }
}

#inspect ⇒ String

Returns a printable version of the match.

Examples:

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

Returns:

  • (String) —

    a printable version of the match



654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
 
# File 'ext/re2/re2.cc', line 654

static VALUE re2_matchdata_inspect(VALUE self) {
  int i;
  re2_matchdata *m;
  re2_pattern *p;
  VALUE match, result;
  ostringstream output;

  Data_Get_Struct(self, re2_matchdata, m);
  Data_Get_Struct(m->regexp, re2_pattern, p);

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

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

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

    match = re2_matchdata_nth_match(i, self);

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

  output << ">";

  result = ENCODED_STR_NEW(output.str().data(), output.str().length(),
      p->pattern->options().encoding() == RE2::Options::EncodingUTF8 ? "UTF-8" : "ISO-8859-1");

  return result;
}

#length ⇒ Fixnum

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:

  • (Fixnum) —

    the number of elements



402
403
404
405
406
407
 
# File 'ext/re2/re2.cc', line 402

static VALUE re2_matchdata_size(VALUE self) {
  re2_matchdata *m;
  Data_Get_Struct(self, re2_matchdata, 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:



478
479
480
481
482
 
# File 'ext/re2/re2.cc', line 478

static VALUE re2_matchdata_regexp(VALUE self) {
  re2_matchdata *m;
  Data_Get_Struct(self, re2_matchdata, m);
  return m->regexp;
}

#size ⇒ Fixnum

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:

  • (Fixnum) —

    the number of elements



402
403
404
405
406
407
 
# File 'ext/re2/re2.cc', line 402

static VALUE re2_matchdata_size(VALUE self) {
  re2_matchdata *m;
  Data_Get_Struct(self, re2_matchdata, 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.



225
226
227
228
229
230
 
# File 'ext/re2/re2.cc', line 225

static VALUE re2_matchdata_string(VALUE self) {
  re2_matchdata *m;
  Data_Get_Struct(self, re2_matchdata, m);

  return m->text;
}

#to_a ⇒ Array<String, nil>

Returns the array of matches.

Examples:

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

Returns:

  • (Array<String, nil>) —

    the array of matches



512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
 
# File 'ext/re2/re2.cc', line 512

static VALUE re2_matchdata_to_a(VALUE self) {
  int i;
  re2_matchdata *m;
  re2_pattern *p;
  re2::StringPiece *match;
  VALUE array;

  Data_Get_Struct(self, re2_matchdata, m);
  Data_Get_Struct(m->regexp, re2_pattern, p);

  array = rb_ary_new2(m->number_of_matches);
  for (i = 0; i < m->number_of_matches; i++) {
    match = &m->matches[i];

    if (match->empty()) {
      rb_ary_push(array, Qnil);
    } else {
      rb_ary_push(array, ENCODED_STR_NEW(match->data(), match->size(),
            p->pattern->options().encoding() == RE2::Options::EncodingUTF8 ? "UTF-8" : "ISO-8859-1"));
    }
  }

  return array;
}

#to_s ⇒ String

Returns the entire matched string.

Returns:

  • (String) —

    the entire matched string



642
643
644
 
# File 'ext/re2/re2.cc', line 642

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