End of Life Ruby 3.1 has reached end of life and gets no more fixes. Switch to Ruby 4.0 →
instance method
Regexp#=~
rxp =~ str → integer or nil
re.c
View on GitHub ↗
VALUE
rb_reg_match(VALUE re, VALUE str)
{
long pos = reg_match_pos(re, &str, 0, NULL);
if (pos < 0) return Qnil;
pos = rb_str_sublen(str, pos);
return LONG2FIX(pos);
}
Match—Matches rxp against str.
Example
/at/ =~ "input data" #=> 7 /ax/ =~ "input data" #=> nil
If =~ is used with a regexp literal with named captures, captured strings (or nil) is assigned to local variables named by the capture names.
Example
/(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ " x = y " p lhs #=> "x" p rhs #=> "y"
If it is not matched, nil is assigned for the variables.
Example
/(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ " x = " p lhs #=> nil p rhs #=> nil
This assignment is implemented in the Ruby parser. The parser detects ‘regexp-literal =~ expression’ for the assignment. The regexp must be a literal without interpolation and placed at left hand side.
The assignment does not occur if the regexp is not a literal.
Example
re = /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ re =~ " x = y " p lhs # undefined local variable p rhs # undefined local variable
A regexp interpolation, #{}, also disables the assignment.
Example
rhs_pat = /(?<rhs>\w+)/ /(?<lhs>\w+)\s*=\s*#{rhs_pat}/ =~ "x = y" p lhs # undefined local variable
The assignment does not occur if the regexp is placed at the right hand side.
Example
" x = y " =~ /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ p lhs, rhs # undefined local variable