Class: MatchData

Inherits:

Object

Object
MatchData

show all

Defined in:: re.c,
re.c

Overview

MatchData encapsulates the result of matching a Regexp against string. It is returned by Regexp#match and String#match, and also stored in a global variable returned by Regexp.last_match.

Usage:

url = 'https://docs.ruby-lang.org/en/2.5.0/MatchData.html'
m = url.match(/(\d\.?)+/)   # => #<MatchData "2.5.0" 1:"0">
m.string                    # => "https://docs.ruby-lang.org/en/2.5.0/MatchData.html"
m.regexp                    # => /(\d\.?)+/
# entire matched substring:
m[0]                        # => "2.5.0"

# Working with unnamed captures
m = url.match(%r{([^/]+)/([^/]+)\.html$})
m.captures                  # => ["2.5.0", "MatchData"]
m[1]                        # => "2.5.0"
m.values_at(1, 2)           # => ["2.5.0", "MatchData"]

# Working with named captures
m = url.match(%r{(?<version>[^/]+)/(?<module>[^/]+)\.html$})
m.captures                  # => ["2.5.0", "MatchData"]
m.named_captures            # => {"version"=>"2.5.0", "module"=>"MatchData"}
m[:version]                 # => "2.5.0"
m.values_at(:version, :module)
                            # => ["2.5.0", "MatchData"]
# Numerical indexes are working, too
m[1]                        # => "2.5.0"
m.values_at(1, 2)           # => ["2.5.0", "MatchData"]

Global variables equivalence

Parts of last MatchData (returned by Regexp.last_match) are also aliased as global variables:

$~ is Regexp.last_match;
$& is Regexp.last_match[ 0 ];
$1, $2, and so on are Regexp.last_match[ i ] (captures by number);
$` is Regexp.last_match.pre_match;
$' is Regexp.last_match.post_match;
$+ is Regexp.last_match[ -1 ] (the last capture).

See also “Special global variables” section in Regexp documentation.

Instance Method Summary collapse

#==(object) ⇒ Boolean

Returns true if object is another MatchData object whose target string, regexp, match, and captures are the same as self, false otherwise.
#[](*args) ⇒ Object

When arguments index, +start and length, or range are given, returns match and captures in the style of Array#[]:.
#begin(n) ⇒ Object

:include: doc/matchdata/begin.rdoc.
#bytebegin(n) ⇒ Object

:include: doc/matchdata/bytebegin.rdoc.
#byteend(n) ⇒ Object

:include: doc/matchdata/byteend.rdoc.
#byteoffset(n) ⇒ Array

Returns a two-element array containing the beginning and ending byte-based offsets of the nth match.
#captures ⇒ Array (also: #deconstruct)

Returns the array of captures, which are all matches except m[0]:.
#deconstruct_keys(array_of_names) ⇒ Hash

Returns a hash of the named captures for the given names.
#end(n) ⇒ Object

:include: doc/matchdata/end.rdoc.
#==(object) ⇒ Boolean

Returns true if object is another MatchData object whose target string, regexp, match, and captures are the same as self, false otherwise.
#hash ⇒ Integer

Returns the integer hash value for self, based on the target string, regexp, match, and captures.
#initialize_copy(orig) ⇒ Object

:nodoc:.
#inspect ⇒ String

Returns a string representation of self:.
#size ⇒ Integer

Returns size of the match array:.
#match(n) ⇒ Object

Returns the matched substring corresponding to the given argument.
#match_length(n) ⇒ Object

Returns the length (in characters) of the matched substring corresponding to the given argument.
#named_captures(symbolize_names: false) ⇒ Hash

Returns a hash of the named captures; each key is a capture name; each value is its captured string or nil:.
#names ⇒ Object

Returns an array of the capture names (see Named Captures):.
#offset(n) ⇒ Object

:include: doc/matchdata/offset.rdoc.
#post_match ⇒ String

Returns the substring of the target string from the end of the first match in self (that is, self[0]) to the end of the string; equivalent to regexp global variable $':.
#pre_match ⇒ String

Returns the substring of the target string from its beginning up to the first match in self (that is, self[0]); equivalent to regexp global variable $`:.
#regexp ⇒ Regexp

Returns the regexp that produced the match:.
#size ⇒ Integer

Returns size of the match array:.
#string ⇒ String

Returns the target string if it was frozen; otherwise, returns a frozen copy of the target string:.
#to_a ⇒ Array

Returns the array of matches:.
#to_s ⇒ String

Returns the matched string:.
#values_at(*indexes) ⇒ Array

Returns match and captures at the given indexes, which may include any mixture of:.

Instance Method Details

#==(object) ⇒ `Boolean`

Returns true if object is another MatchData object whose target string, regexp, match, and captures are the same as self, false otherwise.

Returns:

(Boolean)

# File 're.c', line 3583

static VALUE
match_equal(VALUE match1, VALUE match2)
{
    const struct re_registers *regs1, *regs2;

    if (match1 == match2) return Qtrue;
    if (!RB_TYPE_P(match2, T_MATCH)) return Qfalse;
    if (!RMATCH(match1)->regexp || !RMATCH(match2)->regexp) return Qfalse;
    if (!rb_str_equal(RMATCH(match1)->str, RMATCH(match2)->str)) return Qfalse;
    if (!rb_reg_equal(match_regexp(match1), match_regexp(match2))) return Qfalse;
    regs1 = RMATCH_REGS(match1);
    regs2 = RMATCH_REGS(match2);
    if (regs1->num_regs != regs2->num_regs) return Qfalse;
    if (memcmp(regs1->beg, regs2->beg, regs1->num_regs * sizeof(*regs1->beg))) return Qfalse;
    if (memcmp(regs1->end, regs2->end, regs1->num_regs * sizeof(*regs1->end))) return Qfalse;
    return Qtrue;
}

#[](index) ⇒ `String`^? #[](start, length) ⇒ `Array` #[](range) ⇒ `Array` #[](name) ⇒ `String`^?

When arguments index, +start and length, or range are given, returns match and captures in the style of Array#[]:

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m[0] # => "HX1138"
m[1, 2]  # => ["H", "X"]
m[1..3]  # => ["H", "X", "113"]
m[-3, 2] # => ["X", "113"]

When string or symbol argument name is given, returns the matched substring for the given name:

m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
# => #<MatchData "hoge" foo:"h" bar:"ge">
m['foo'] # => "h"
m[:bar]  # => "ge"

If multiple captures have the same name, returns the last matched substring.

m = /(?<foo>.)(?<foo>.+)/.match("hoge")
# => #<MatchData "hoge" foo:"h" foo:"oge">
m[:foo] #=> "oge"

m = /\W(?<foo>.+)|\w(?<foo>.+)|(?<foo>.+)/.match("hoge")
#<MatchData "hoge" foo:nil foo:"oge" foo:nil>
m[:foo] #=> "oge"

Overloads:

#[](index) ⇒ String^?
Returns:
- (String, nil)
#[](start, length) ⇒ Array
Returns:
- (Array)
#[](range) ⇒ Array
Returns:
- (Array)
#[](name) ⇒ String^?
Returns:
- (String, nil)

# File 're.c', line 2234

static VALUE
match_aref(int argc, VALUE *argv, VALUE match)
{
    VALUE idx, length;

    match_check(match);
    rb_scan_args(argc, argv, "11", &idx, &length);

    if (NIL_P(length)) {
        if (FIXNUM_P(idx)) {
            return rb_reg_nth_match(FIX2INT(idx), match);
        }
        else {
            int num = namev_to_backref_number(RMATCH_REGS(match), RMATCH(match)->regexp, idx);
            if (num >= 0) {
                return rb_reg_nth_match(num, match);
            }
            else {
                return match_ary_aref(match, idx, Qnil);
            }
        }
    }
    else {
        long beg = NUM2LONG(idx);
        long len = NUM2LONG(length);
        long num_regs = RMATCH_REGS(match)->num_regs;
        if (len < 0) {
            return Qnil;
        }
        if (beg < 0) {
            beg += num_regs;
            if (beg < 0) return Qnil;
        }
        else if (beg > num_regs) {
            return Qnil;
        }
        if (beg+len > num_regs) {
            len = num_regs - beg;
        }
        return match_ary_subseq(match, beg, len, Qnil);
    }
}

#begin(n) ⇒ `Integer` #begin(name) ⇒ `Integer`

:include: doc/matchdata/begin.rdoc

Overloads:

#begin(n) ⇒ Integer
Returns:
- (Integer)
#begin(name) ⇒ Integer
Returns:
- (Integer)

# File 're.c', line 1356

static VALUE
match_begin(VALUE match, VALUE n)
{
    int i = match_backref_number(match, n);
    struct re_registers *regs = RMATCH_REGS(match);

    match_check(match);
    backref_number_check(regs, i);

    if (BEG(i) < 0)
        return Qnil;

    update_char_offset(match);
    return LONG2NUM(RMATCH_EXT(match)->char_offset[i].beg);
}

#bytebegin(n) ⇒ `Integer` #bytebegin(name) ⇒ `Integer`

:include: doc/matchdata/bytebegin.rdoc

Overloads:

#bytebegin(n) ⇒ Integer
Returns:
- (Integer)
#bytebegin(name) ⇒ Integer
Returns:
- (Integer)

# File 're.c', line 1308

static VALUE
match_bytebegin(VALUE match, VALUE n)
{
    int i = match_backref_number(match, n);
    struct re_registers *regs = RMATCH_REGS(match);

    match_check(match);
    backref_number_check(regs, i);

    if (BEG(i) < 0)
        return Qnil;
    return LONG2NUM(BEG(i));
}

#byteend(n) ⇒ `Integer` #byteend(name) ⇒ `Integer`

:include: doc/matchdata/byteend.rdoc

Overloads:

#byteend(n) ⇒ Integer
Returns:
- (Integer)
#byteend(name) ⇒ Integer
Returns:
- (Integer)

# File 're.c', line 1332

static VALUE
match_byteend(VALUE match, VALUE n)
{
    int i = match_backref_number(match, n);
    struct re_registers *regs = RMATCH_REGS(match);

    match_check(match);
    backref_number_check(regs, i);

    if (BEG(i) < 0)
        return Qnil;
    return LONG2NUM(END(i));
}

#byteoffset(n) ⇒ `Array`

Returns a two-element array containing the beginning and ending byte-based offsets of the nth match. n can be a string or symbol to reference a named capture.

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
m.byteoffset(0)      #=> [1, 7]
m.byteoffset(4)      #=> [6, 7]

m = /(?<foo>.)(.)(?<bar>.)/.match("hoge")
p m.byteoffset(:foo) #=> [0, 1]
p m.byteoffset(:bar) #=> [2, 3]

Returns:

(Array)

# File 're.c', line 1284

static VALUE
match_byteoffset(VALUE match, VALUE n)
{
    int i = match_backref_number(match, n);
    struct re_registers *regs = RMATCH_REGS(match);

    match_check(match);
    backref_number_check(regs, i);

    if (BEG(i) < 0)
        return rb_assoc_new(Qnil, Qnil);
    return rb_assoc_new(LONG2NUM(BEG(i)), LONG2NUM(END(i)));
}

#captures ⇒ `Array` Also known as: deconstruct

Returns the array of captures, which are all matches except m[0]:

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m[0]       # => "HX1138"
m.captures # => ["H", "X", "113", "8"]

Related: MatchData.to_a.

Returns:

(Array)

# File 're.c', line 2122

static VALUE
match_captures(VALUE match)
{
    return match_array(match, 1);
}

#deconstruct_keys(array_of_names) ⇒ `Hash`

Returns a hash of the named captures for the given names.

m = /(?<hours>\d{2}):(?<minutes>\d{2}):(?<seconds>\d{2})/.match("18:37:22")
m.deconstruct_keys([:hours, :minutes]) # => {:hours => "18", :minutes => "37"}
m.deconstruct_keys(nil) # => {:hours => "18", :minutes => "37", :seconds => "22"}

Returns an empty hash if no named captures were defined:

m = /(\d{2}):(\d{2}):(\d{2})/.match("18:37:22")
m.deconstruct_keys(nil) # => {}

Returns:

(Hash)

# File 're.c', line 2477

static VALUE
match_deconstruct_keys(VALUE match, VALUE keys)
{
    VALUE h;
    long i;

    match_check(match);

    if (NIL_P(RMATCH(match)->regexp)) {
        return rb_hash_new_with_size(0);
    }

    if (NIL_P(keys)) {
        h = rb_hash_new_with_size(onig_number_of_names(RREGEXP_PTR(RMATCH(match)->regexp)));

        struct MEMO *memo;
        memo = MEMO_NEW(h, match, 1);

        onig_foreach_name(RREGEXP_PTR(RMATCH(match)->regexp), match_named_captures_iter, (void*)memo);

        return h;
    }

    Check_Type(keys, T_ARRAY);

    if (onig_number_of_names(RREGEXP_PTR(RMATCH(match)->regexp)) < RARRAY_LEN(keys)) {
        return rb_hash_new_with_size(0);
    }

    h = rb_hash_new_with_size(RARRAY_LEN(keys));

    for (i=0; i<RARRAY_LEN(keys); i++) {
        VALUE key = RARRAY_AREF(keys, i);
        VALUE name;

        Check_Type(key, T_SYMBOL);

        name = rb_sym2str(key);

        int num = NAME_TO_NUMBER(RMATCH_REGS(match), RMATCH(match)->regexp, RMATCH(match)->regexp,
                         RSTRING_PTR(name), RSTRING_END(name));

        if (num >= 0) {
            rb_hash_aset(h, key, rb_reg_nth_match(num, match));
        }
        else {
            return h;
        }
    }

    return h;
}

#end(n) ⇒ `Integer` #end(name) ⇒ `Integer`

:include: doc/matchdata/end.rdoc

Overloads:

#end(n) ⇒ Integer
Returns:
- (Integer)
#end(name) ⇒ Integer
Returns:
- (Integer)

# File 're.c', line 1382

static VALUE
match_end(VALUE match, VALUE n)
{
    int i = match_backref_number(match, n);
    struct re_registers *regs = RMATCH_REGS(match);

    match_check(match);
    backref_number_check(regs, i);

    if (BEG(i) < 0)
        return Qnil;

    update_char_offset(match);
    return LONG2NUM(RMATCH_EXT(match)->char_offset[i].end);
}

#==(object) ⇒ `Boolean`

Returns true if object is another MatchData object whose target string, regexp, match, and captures are the same as self, false otherwise.

Returns:

(Boolean)

# File 're.c', line 3583

static VALUE
match_equal(VALUE match1, VALUE match2)
{
    const struct re_registers *regs1, *regs2;

    if (match1 == match2) return Qtrue;
    if (!RB_TYPE_P(match2, T_MATCH)) return Qfalse;
    if (!RMATCH(match1)->regexp || !RMATCH(match2)->regexp) return Qfalse;
    if (!rb_str_equal(RMATCH(match1)->str, RMATCH(match2)->str)) return Qfalse;
    if (!rb_reg_equal(match_regexp(match1), match_regexp(match2))) return Qfalse;
    regs1 = RMATCH_REGS(match1);
    regs2 = RMATCH_REGS(match2);
    if (regs1->num_regs != regs2->num_regs) return Qfalse;
    if (memcmp(regs1->beg, regs2->beg, regs1->num_regs * sizeof(*regs1->beg))) return Qfalse;
    if (memcmp(regs1->end, regs2->end, regs1->num_regs * sizeof(*regs1->end))) return Qfalse;
    return Qtrue;
}

#hash ⇒ `Integer`

Returns the integer hash value for self, based on the target string, regexp, match, and captures.

#initialize_copy(orig) ⇒ `Object`

:nodoc:

# File 're.c', line 1088

static VALUE
match_init_copy(VALUE obj, VALUE orig)
{
    rb_matchext_t *rm;

    if (!OBJ_INIT_COPY(obj, orig)) return obj;

    RB_OBJ_WRITE(obj, &RMATCH(obj)->str, RMATCH(orig)->str);
    RB_OBJ_WRITE(obj, &RMATCH(obj)->regexp, RMATCH(orig)->regexp);

    rm = RMATCH_EXT(obj);
    if (rb_reg_region_copy(&rm->regs, RMATCH_REGS(orig)))
        rb_memerror();

    if (RMATCH_EXT(orig)->char_offset_num_allocated) {
        if (rm->char_offset_num_allocated < rm->regs.num_regs) {
            REALLOC_N(rm->char_offset, struct rmatch_offset, rm->regs.num_regs);
            rm->char_offset_num_allocated = rm->regs.num_regs;
        }
        MEMCPY(rm->char_offset, RMATCH_EXT(orig)->char_offset,
               struct rmatch_offset, rm->regs.num_regs);
        RB_GC_GUARD(orig);
    }

    return obj;
}

#inspect ⇒ `String`

Returns a string representation of self:

m = /.$/.match("foo")
# => #<MatchData "o">
m.inspect # => "#<MatchData \"o\">"

m = /(.)(.)(.)/.match("foo")
# => #<MatchData "foo" 1:"f" 2:"o" 3:"o">
m.inspect # => "#<MatchData \"foo\" 1:\"f\" 2:\"o\

m = /(.)(.)?(.)/.match("fo")
# => #<MatchData "fo" 1:"f" 2:nil 3:"o">
m.inspect # => "#<MatchData \"fo\" 1:\"f\" 2:nil 3:\"o\">"

Related: MatchData#to_s.

Returns:

(String)

# File 're.c', line 2590

static VALUE
match_inspect(VALUE match)
{
    VALUE cname = rb_class_path(rb_obj_class(match));
    VALUE str;
    int i;
    struct re_registers *regs = RMATCH_REGS(match);
    int num_regs = regs->num_regs;
    struct backref_name_tag *names;
    VALUE regexp = RMATCH(match)->regexp;

    if (regexp == 0) {
        return rb_sprintf("#<%"PRIsVALUE":%p>", cname, (void*)match);
    }
    else if (NIL_P(regexp)) {
        return rb_sprintf("#<%"PRIsVALUE": %"PRIsVALUE">",
                          cname, rb_reg_nth_match(0, match));
    }

    names = ALLOCA_N(struct backref_name_tag, num_regs);
    MEMZERO(names, struct backref_name_tag, num_regs);

    onig_foreach_name(RREGEXP_PTR(regexp),
            match_inspect_name_iter, names);

    str = rb_str_buf_new2("#<");
    rb_str_append(str, cname);

    for (i = 0; i < num_regs; i++) {
        VALUE v;
        rb_str_buf_cat2(str, " ");
        if (0 < i) {
            if (names[i].name)
                rb_str_buf_cat(str, (const char *)names[i].name, names[i].len);
            else {
                rb_str_catf(str, "%d", i);
            }
            rb_str_buf_cat2(str, ":");
        }
        v = rb_reg_nth_match(i, match);
        if (NIL_P(v))
            rb_str_buf_cat2(str, "nil");
        else
            rb_str_buf_append(str, rb_str_inspect(v));
    }
    rb_str_buf_cat2(str, ">");

    return str;
}

#size ⇒ `Integer`

Returns size of the match array:

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m.size # => 5

Returns:

(Integer)

# File 're.c', line 1183

static VALUE
match_size(VALUE match)
{
    match_check(match);
    return INT2FIX(RMATCH_REGS(match)->num_regs);
}

#match(n) ⇒ `String`^? #match(name) ⇒ `String`^?

Returns the matched substring corresponding to the given argument.

When non-negative argument n is given, returns the matched substring for the nth match:

m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8" 5:nil>
m.match(0) # => "HX1138"
m.match(4) # => "8"
m.match(5) # => nil

When string or symbol argument name is given, returns the matched substring for the given name:

m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
# => #<MatchData "hoge" foo:"h" bar:"ge">
m.match('foo') # => "h"
m.match(:bar)  # => "ge"

Overloads:

#match(n) ⇒ String^?
Returns:
- (String, nil)
#match(name) ⇒ String^?
Returns:
- (String, nil)

# File 're.c', line 1424

static VALUE
match_nth(VALUE match, VALUE n)
{
    int i = match_backref_number(match, n);
    struct re_registers *regs = RMATCH_REGS(match);

    backref_number_check(regs, i);

    long start = BEG(i), end = END(i);
    if (start < 0)
        return Qnil;

    return rb_str_subseq(RMATCH(match)->str, start, end - start);
}

#match_length(n) ⇒ `Integer`^? #match_length(name) ⇒ `Integer`^?

Returns the length (in characters) of the matched substring corresponding to the given argument.

When non-negative argument n is given, returns the length of the matched substring for the nth match:

m = /(.)(.)(\d+)(\d)(\w)?/.match("THX1138.")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8" 5:nil>
m.match_length(0) # => 6
m.match_length(4) # => 1
m.match_length(5) # => nil

When string or symbol argument name is given, returns the length of the matched substring for the named match:

m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
# => #<MatchData "hoge" foo:"h" bar:"ge">
m.match_length('foo') # => 1
m.match_length(:bar)  # => 2

Overloads:

#match_length(n) ⇒ Integer^?
Returns:
- (Integer, nil)
#match_length(name) ⇒ Integer^?
Returns:
- (Integer, nil)

# File 're.c', line 1468

static VALUE
match_nth_length(VALUE match, VALUE n)
{
    int i = match_backref_number(match, n);
    struct re_registers *regs = RMATCH_REGS(match);

    match_check(match);
    backref_number_check(regs, i);

    if (BEG(i) < 0)
        return Qnil;

    update_char_offset(match);
    const struct rmatch_offset *const ofs =
        &RMATCH_EXT(match)->char_offset[i];
    return LONG2NUM(ofs->end - ofs->beg);
}

#named_captures(symbolize_names: false) ⇒ `Hash`

Returns a hash of the named captures; each key is a capture name; each value is its captured string or nil:

m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
# => #<MatchData "hoge" foo:"h" bar:"ge">
m.named_captures # => {"foo"=>"h", "bar"=>"ge"}

m = /(?<a>.)(?<b>.)/.match("01")
# => #<MatchData "01" a:"0" b:"1">
m.named_captures #=> {"a" => "0", "b" => "1"}

m = /(?<a>.)(?<b>.)?/.match("0")
# => #<MatchData "0" a:"0" b:nil>
m.named_captures #=> {"a" => "0", "b" => nil}

m = /(?<a>.)(?<a>.)/.match("01")
# => #<MatchData "01" a:"0" a:"1">
m.named_captures #=> {"a" => "1"}

If keyword argument symbolize_names is given a true value, the keys in the resulting hash are Symbols:

m = /(?<a>.)(?<a>.)/.match("01")
# => #<MatchData "01" a:"0" a:"1">
m.named_captures(symbolize_names: true) #=> {:a => "1"}

Returns:

(Hash)

# File 're.c', line 2424

static VALUE
match_named_captures(int argc, VALUE *argv, VALUE match)
{
    VALUE hash;
    struct MEMO *memo;

    match_check(match);
    if (NIL_P(RMATCH(match)->regexp))
        return rb_hash_new();

    VALUE opt;
    VALUE symbolize_names = 0;

    rb_scan_args(argc, argv, "0:", &opt);

    if (!NIL_P(opt)) {
        static ID keyword_ids[1];

        VALUE symbolize_names_val;

        if (!keyword_ids[0]) {
            keyword_ids[0] = rb_intern_const("symbolize_names");
        }
        rb_get_kwargs(opt, keyword_ids, 0, 1, &symbolize_names_val);
        if (!UNDEF_P(symbolize_names_val) && RTEST(symbolize_names_val)) {
            symbolize_names = 1;
        }
    }

    hash = rb_hash_new();
    memo = MEMO_NEW(hash, match, symbolize_names);

    onig_foreach_name(RREGEXP(RMATCH(match)->regexp)->ptr, match_named_captures_iter, (void*)memo);

    return hash;
}

#names ⇒ `Object`

Returns an array of the capture names (see Named Captures):

m = /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge")
# => #<MatchData "hog" foo:"h" bar:"o" baz:"g">
m.names # => ["foo", "bar", "baz"]

m = /foo/.match('foo') # => #<MatchData "foo">
m.names # => [] # No named captures.

Equivalent to:

m = /(?<foo>.)(?<bar>.)(?<baz>.)/.match("hoge")
m.regexp.names # => ["foo", "bar", "baz"]

# File 're.c', line 1162

static VALUE
match_names(VALUE match)
{
    match_check(match);
    if (NIL_P(RMATCH(match)->regexp))
        return rb_ary_new_capa(0);
    return rb_reg_names(RMATCH(match)->regexp);
}

#offset(n) ⇒ `Array` #offset(name) ⇒ `Array`

:include: doc/matchdata/offset.rdoc

Overloads:

#offset(n) ⇒ Array
Returns:
- (Array)
#offset(name) ⇒ Array
Returns:
- (Array)

# File 're.c', line 1249

static VALUE
match_offset(VALUE match, VALUE n)
{
    int i = match_backref_number(match, n);
    struct re_registers *regs = RMATCH_REGS(match);

    match_check(match);
    backref_number_check(regs, i);

    if (BEG(i) < 0)
        return rb_assoc_new(Qnil, Qnil);

    update_char_offset(match);
    return rb_assoc_new(LONG2NUM(RMATCH_EXT(match)->char_offset[i].beg),
                        LONG2NUM(RMATCH_EXT(match)->char_offset[i].end));
}

#post_match ⇒ `String`

Returns the substring of the target string from the end of the first match in self (that is, self[0]) to the end of the string; equivalent to regexp global variable $':

m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m[0]         # => "HX1138"
m.post_match # => ": The Movie"\

Related: MatchData.pre_match.

Returns:

(String)

# File 're.c', line 1986

VALUE
rb_reg_match_post(VALUE match)
{
    VALUE str;
    long pos;
    struct re_registers *regs;

    if (NIL_P(match)) return Qnil;
    match_check(match);
    regs = RMATCH_REGS(match);
    if (BEG(0) == -1) return Qnil;
    str = RMATCH(match)->str;
    pos = END(0);
    str = rb_str_subseq(str, pos, RSTRING_LEN(str) - pos);
    return str;
}

#pre_match ⇒ `String`

Returns the substring of the target string from its beginning up to the first match in self (that is, self[0]); equivalent to regexp global variable $`:

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m[0]        # => "HX1138"
m.pre_match # => "T"

Related: MatchData#post_match.

Returns:

(String)

# File 're.c', line 1953

VALUE
rb_reg_match_pre(VALUE match)
{
    VALUE str;
    struct re_registers *regs;

    if (NIL_P(match)) return Qnil;
    match_check(match);
    regs = RMATCH_REGS(match);
    if (BEG(0) == -1) return Qnil;
    str = rb_str_subseq(RMATCH(match)->str, 0, BEG(0));
    return str;
}

#regexp ⇒ `Regexp`

Returns the regexp that produced the match:

m = /a.*b/.match("abc") # => #<MatchData "ab">
m.regexp                # => /a.*b/

Returns:

(Regexp)

# File 're.c', line 1127

static VALUE
match_regexp(VALUE match)
{
    VALUE regexp;
    match_check(match);
    regexp = RMATCH(match)->regexp;
    if (NIL_P(regexp)) {
        VALUE str = rb_reg_nth_match(0, match);
        regexp = rb_reg_regcomp(rb_reg_quote(str));
        RB_OBJ_WRITE(match, &RMATCH(match)->regexp, regexp);
    }
    return regexp;
}

#size ⇒ `Integer`

Returns size of the match array:

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m.size # => 5

Returns:

(Integer)

# File 're.c', line 1183

static VALUE
match_size(VALUE match)
{
    match_check(match);
    return INT2FIX(RMATCH_REGS(match)->num_regs);
}

#string ⇒ `String`

Returns the target string if it was frozen; otherwise, returns a frozen copy of the target string:

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m.string # => "THX1138."

Returns:

(String)

# File 're.c', line 2543

static VALUE
match_string(VALUE match)
{
    match_check(match);
    return RMATCH(match)->str;	/* str is frozen */
}

#to_a ⇒ `Array`

Returns the array of matches:

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m.to_a # => ["HX1138", "H", "X", "113", "8"]

Related: MatchData#captures.

Returns:

(Array)

# File 're.c', line 2100

static VALUE
match_to_a(VALUE match)
{
    return match_array(match, 0);
}

#to_s ⇒ `String`

Returns the matched string:

m = /(.)(.)(\d+)(\d)/.match("THX1138.")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m.to_s # => "HX1138"

m = /(?<foo>.)(.)(?<bar>.+)/.match("hoge")
# => #<MatchData "hoge" foo:"h" bar:"ge">
m.to_s # => "hoge"

Related: MatchData.inspect.

Returns:

(String)

# File 're.c', line 2348

static VALUE
match_to_s(VALUE match)
{
    VALUE str = rb_reg_last_match(match_check(match));

    if (NIL_P(str)) str = rb_str_new(0,0);
    return str;
}

#values_at(*indexes) ⇒ `Array`

Returns match and captures at the given indexes, which may include any mixture of:

Integers.
Ranges.
Names (strings and symbols).

Examples:

m = /(.)(.)(\d+)(\d)/.match("THX1138: The Movie")
# => #<MatchData "HX1138" 1:"H" 2:"X" 3:"113" 4:"8">
m.values_at(0, 2, -2) # => ["HX1138", "X", "113"]
m.values_at(1..2, -1) # => ["H", "X", "8"]

m = /(?<a>\d+) *(?<op>[+\-*\/]) *(?<b>\d+)/.match("1 + 2")
# => #<MatchData "1 + 2" a:"1" op:"+" b:"2">
m.values_at(0, 1..2, :a, :b, :op)
# => ["1 + 2", "1", "+", "1", "2", "+"]

Returns:

(Array)

# File 're.c', line 2303

static VALUE
match_values_at(int argc, VALUE *argv, VALUE match)
{
    VALUE result;
    int i;

    match_check(match);
    result = rb_ary_new2(argc);

    for (i=0; i<argc; i++) {
        if (FIXNUM_P(argv[i])) {
            rb_ary_push(result, rb_reg_nth_match(FIX2INT(argv[i]), match));
        }
        else {
            int num = namev_to_backref_number(RMATCH_REGS(match), RMATCH(match)->regexp, argv[i]);
            if (num >= 0) {
                rb_ary_push(result, rb_reg_nth_match(num, match));
            }
            else {
                match_ary_aref(match, argv[i], result);
            }
        }
    }
    return result;
}

Class: MatchData

Overview

Global variables equivalence

Instance Method Summary collapse

Instance Method Details

#==(object) ⇒ Boolean

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

#begin(n) ⇒ Integer #begin(name) ⇒ Integer

#bytebegin(n) ⇒ Integer #bytebegin(name) ⇒ Integer

#byteend(n) ⇒ Integer #byteend(name) ⇒ Integer

#byteoffset(n) ⇒ Array

#captures ⇒ Array Also known as: deconstruct

#deconstruct_keys(array_of_names) ⇒ Hash

#end(n) ⇒ Integer #end(name) ⇒ Integer

#==(object) ⇒ Boolean

#hash ⇒ Integer

#initialize_copy(orig) ⇒ Object

#inspect ⇒ String

#size ⇒ Integer

#match(n) ⇒ String? #match(name) ⇒ String?

#match_length(n) ⇒ Integer? #match_length(name) ⇒ Integer?

#named_captures(symbolize_names: false) ⇒ Hash

#names ⇒ Object

#offset(n) ⇒ Array #offset(name) ⇒ Array

#post_match ⇒ String

#pre_match ⇒ String

#regexp ⇒ Regexp

#size ⇒ Integer

#string ⇒ String

#to_a ⇒ Array

#to_s ⇒ String

#values_at(*indexes) ⇒ Array

#==(object) ⇒ `Boolean`

#[](index) ⇒ `String`^? #[](start, length) ⇒ `Array` #[](range) ⇒ `Array` #[](name) ⇒ `String`^?

#begin(n) ⇒ `Integer` #begin(name) ⇒ `Integer`

#bytebegin(n) ⇒ `Integer` #bytebegin(name) ⇒ `Integer`

#byteend(n) ⇒ `Integer` #byteend(name) ⇒ `Integer`

#byteoffset(n) ⇒ `Array`

#captures ⇒ `Array` Also known as: deconstruct

#deconstruct_keys(array_of_names) ⇒ `Hash`

#end(n) ⇒ `Integer` #end(name) ⇒ `Integer`

#==(object) ⇒ `Boolean`

#hash ⇒ `Integer`

#initialize_copy(orig) ⇒ `Object`

#inspect ⇒ `String`

#size ⇒ `Integer`

#match(n) ⇒ `String`^? #match(name) ⇒ `String`^?

#match_length(n) ⇒ `Integer`^? #match_length(name) ⇒ `Integer`^?

#named_captures(symbolize_names: false) ⇒ `Hash`

#names ⇒ `Object`

#offset(n) ⇒ `Array` #offset(name) ⇒ `Array`

#post_match ⇒ `String`

#pre_match ⇒ `String`

#regexp ⇒ `Regexp`

#size ⇒ `Integer`

#string ⇒ `String`

#to_a ⇒ `Array`

#to_s ⇒ `String`

#values_at(*indexes) ⇒ `Array`