Class: Regexp

Inherits:
Object show all
Defined in:
re.c,
re.c

Overview

A Regexp holds a regular expression, used to match a pattern against strings. Regexps are created using the /.../ and %r{...} literals, and by the Regexp::new constructor.

Constant Summary collapse

IGNORECASE = 
INT2FIX(RE_OPTION_IGNORECASE)
EXTENDED = 
INT2FIX(RE_OPTION_EXTENDED)
MULTILINE = 
INT2FIX(RE_OPTION_MULTILINE)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#new(string[, options [, lang]]) ⇒ Regexp #new(regexp) ⇒ Regexp #compile(string[, options [, lang]]) ⇒ Regexp #compile(regexp) ⇒ Regexp

Constructs a new regular expression from pattern, which can be either a String or a Regexp (in which case that regexp’s options are propagated, and new options may not be specified (a change as of Ruby 1.8). If options is a Fixnum, it should be one or more of the constants Regexp::EXTENDED, Regexp::IGNORECASE, and Regexp::MULTILINE, or-ed together. Otherwise, if options is not nil, the regexp will be case insensitive. The lang parameter enables multibyte support for the regexp: ‘n’, ‘N’ = none, ‘e’, ‘E’ = EUC, ‘s’, ‘S’ = SJIS, ‘u’, ‘U’ = UTF-8.

r1 = Regexp.new('^a-z+:\\s+\w+')           #=> /^a-z+:\s+\w+/
r2 = Regexp.new('cat', true)               #=> /cat/i
r3 = Regexp.new('dog', Regexp::EXTENDED)   #=> /dog/x
r4 = Regexp.new(r2)                        #=> /cat/i

Overloads:

  • #new(string[, options [, lang]]) ⇒ Regexp
  • #new(regexp) ⇒ Regexp
  • #compile(string[, options [, lang]]) ⇒ Regexp
  • #compile(regexp) ⇒ Regexp 


1707
1708
1709
 
# File 're.c', line 1707

static VALUE
rb_reg_initialize_m(argc, argv, self)
int argc;

Class Method Details

.compile ⇒ Object

Synonym for Regexp.new

.escape(str) ⇒ String .quote(str) ⇒ String

Escapes any characters that would have special meaning in a regular expression. Returns a new escaped string, or self if no characters are escaped. For any string, Regexp.escape(str)=~str will be true.

Regexp.escape('\\*?{}.')   #=> \\\\\*\?\{\}\.

Overloads:



1879
1880
1881
 
# File 're.c', line 1879

static VALUE
rb_reg_s_quote(argc, argv)
int argc;

.last_match ⇒ MatchData .last_match(fixnum) ⇒ String

The first form returns the MatchData object generated by the last successful pattern match. Equivalent to reading the global variable $~. The second form returns the nth field in this MatchData object.

/c(.)t/ =~ 'cat'       #=> 0
Regexp.last_match      #=> #<MatchData:0x401b3d30>
Regexp.last_match(0)   #=> "cat"
Regexp.last_match(1)   #=> "a"
Regexp.last_match(2)   #=> nil

Overloads:



2271
2272
2273
 
# File 're.c', line 2271

static VALUE
rb_reg_s_last_match(argc, argv)
int argc;

.escape(str) ⇒ String .quote(str) ⇒ String

Escapes any characters that would have special meaning in a regular expression. Returns a new escaped string, or self if no characters are escaped. For any string, Regexp.escape(str)=~str will be true.

Regexp.escape('\\*?{}.')   #=> \\\\\*\?\{\}\.

Overloads:



1879
1880
1881
 
# File 're.c', line 1879

static VALUE
rb_reg_s_quote(argc, argv)
int argc;

.union(pat1, pat2, ...) ⇒ Regexp .union(pats_ary) ⇒ Regexp

Return a Regexp object that is the union of the given patterns, i.e., will match any of its parts. The patterns can be Regexp objects, in which case their options will be preserved, or Strings. If no patterns are given, returns /(?!)/.

Regexp.union                         #=> /(?!)/
Regexp.union("penzance")             #=> /penzance/
Regexp.union("a+b*c")                #=> /a\+b\*c/
Regexp.union("skiing", "sledding")   #=> /skiing|sledding/
Regexp.union(["skiing", "sledding"]) #=> /skiing|sledding/
Regexp.union(/dogs/, /cats/i)        #=> /(?-mix:dogs)|(?i-mx:cats)/

Overloads:



2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
 
# File 're.c', line 2042

static VALUE
rb_reg_s_union_m(VALUE self, VALUE args)
{
    VALUE v;
    if (RARRAY_LEN(args) == 1 &&
        !NIL_P(v = rb_check_array_type(rb_ary_entry(args, 0)))) {
        return rb_reg_s_union(self, v);
    }
    return rb_reg_s_union(self, args);
}

Instance Method Details

#==(other_rxp) ⇒ Boolean #eql?(other_rxp) ⇒ Boolean

Equality—Two regexps are equal if their patterns are identical, they have the same character set code, and their casefold? values are the same.

/abc/  == /abc/x   #=> false
/abc/  == /abc/i   #=> false
/abc/u == /abc/n   #=> false

Overloads:

  • #==(other_rxp) ⇒ Boolean

    Returns:

    • (Boolean)
  • #eql?(other_rxp) ⇒ Boolean

    Returns:

    • (Boolean) 


1536
1537
1538
 
# File 're.c', line 1536

static VALUE
rb_reg_equal(re1, re2)
VALUE re1, re2;

#===(str) ⇒ Boolean

Case Equality—Synonym for Regexp#=~ used in case statements.

a = "HELLO"
case a
when /^[a-z]*$/; print "Lower case\n"
when /^[A-Z]*$/; print "Upper case\n"
else;            print "Mixed case\n"
end

produces:

Upper case

Returns:

  • (Boolean) 


1601
1602
1603
 
# File 're.c', line 1601

VALUE
rb_reg_eqq(re, str)
VALUE re, str;

#match(str) ⇒ MatchData?

Returns a MatchData object describing the match, or nil if there was no match. This is equivalent to retrieving the value of the special variable $~ following a normal match.

/(.)(.)(.)/.match("abc")[2]   #=> "b"

Returns:



1564
1565
1566
 
# File 're.c', line 1564

VALUE
rb_reg_match(re, str)
VALUE re, str;

#casefold? ⇒ Boolean

Returns the value of the case-insensitive flag.

Returns:

  • (Boolean) 


545
546
547
 
# File 're.c', line 545

static VALUE
rb_reg_casefold_p(re)
VALUE re;

#==(other_rxp) ⇒ Boolean #eql?(other_rxp) ⇒ Boolean

Equality—Two regexps are equal if their patterns are identical, they have the same character set code, and their casefold? values are the same.

/abc/  == /abc/x   #=> false
/abc/  == /abc/i   #=> false
/abc/u == /abc/n   #=> false

Overloads:

  • #==(other_rxp) ⇒ Boolean

    Returns:

    • (Boolean)
  • #eql?(other_rxp) ⇒ Boolean

    Returns:

    • (Boolean) 


1536
1537
1538
 
# File 're.c', line 1536

static VALUE
rb_reg_equal(re1, re2)
VALUE re1, re2;

#hash ⇒ Fixnum

Produce a hash based on the text and options of this regular expression.

Returns:



1502
1503
1504
 
# File 're.c', line 1502

static VALUE
rb_reg_hash(re)
VALUE re;

#initialize_copy ⇒ Object

:nodoc:



2054
2055
2056
 
# File 're.c', line 2054

static VALUE
rb_reg_init_copy(copy, re)
VALUE copy, re;

#inspect ⇒ String

Produce a nicely formatted string-version of rxp. Perhaps surprisingly, #inspect actually produces the more natural version of the string than #to_s.

/ab+c/ix.to_s         #=> /ab+c/ix

Returns:



402
403
404
 
# File 're.c', line 402

static VALUE
rb_reg_inspect(re)
VALUE re;

#kcode ⇒ String

Returns the character set code for the regexp.

Returns:



594
595
596
 
# File 're.c', line 594

static VALUE
rb_reg_kcode_m(re)
VALUE re;

#match(str) ⇒ MatchData?

Returns a MatchData object describing the match, or nil if there was no match. This is equivalent to retrieving the value of the special variable $~ following a normal match.

/(.)(.)(.)/.match("abc")[2]   #=> "b"

Returns:



1665
1666
1667
 
# File 're.c', line 1665

static VALUE
rb_reg_match_m(re, str)
VALUE re, str;

#options ⇒ Fixnum

Returns the set of bits corresponding to the options used when creating this Regexp (see Regexp::new for details. Note that additional bits may be set in the returned options: these are used internally by the regular expression code. These extra bits are ignored if the options are passed to Regexp::new.

Regexp::IGNORECASE                  #=> 1
Regexp::EXTENDED                    #=> 2
Regexp::MULTILINE                   #=> 4

/cat/.options                       #=> 128
/cat/ix.options                     #=> 131
Regexp.new('cat', true).options     #=> 129
Regexp.new('cat', 0, 's').options   #=> 384

r = /cat/ix
Regexp.new(r.source, r.options)     #=> /cat/ix

Returns:



578
579
580
 
# File 're.c', line 578

static VALUE
rb_reg_options_m(re)
VALUE re;

#source ⇒ String

Returns the original string of the pattern.

/ab+c/ix.source   #=> "ab+c"

Returns:



379
380
381
 
# File 're.c', line 379

static VALUE
rb_reg_source(re)
VALUE re;

#to_s ⇒ String

Returns a string containing the regular expression and its options (using the (?xxx:yyy) notation. This string can be fed back in to Regexp::new to a regular expression with the same semantics as the original. (However, Regexp#== may not return true when comparing the two, as the source of the regular expression itself may differ, as the example shows). Regexp#inspect produces a generally more readable version of rxp.

r1 = /ab+c/ix         #=> /ab+c/ix
s1 = r1.to_s          #=> "(?ix-m:ab+c)"
r2 = Regexp.new(s1)   #=> /(?ix-m:ab+c)/
r1 == r2              #=> false
r1.source             #=> "ab+c"
r2.source             #=> "(?ix-m:ab+c)"

Returns:



431
432
433
 
# File 're.c', line 431

static VALUE
rb_reg_to_s(re)
VALUE re;

#~(rxp) ⇒ Integer?

Match—Matches rxp against the contents of $_. Equivalent to rxp =~ $_.

$_ = "input data"
~ /at/   #=> 7

Returns:



1634
1635
1636
 
# File 're.c', line 1634

VALUE
rb_reg_match2(re)
VALUE re;