[JavaScript 1.2 Docs] [Regular Expressions Objects] [The RegExp Object] [Regular Expression Objects]

Regular Expression Objects

This section describes the regular expression object and its methods.

compile method
exec method
test method

Core object. A regular expression object contains the pattern of a regular expression. It has properties and methods for using that regular expression to work with strings. In addition to the properties of an individual regular expression object, the predefined RegExp object has properties that are set whenever any regular expression is invoked.

Syntax

The literal text format is compiled into a compact and efficient internal representation.

Literal notation

regexp = /pattern/[i|g|gi]

Constructed

regexp = new RegExp("pattern", ["i"|"g"|"gi"])

Parameters

regexp is the name of the regular expression object.

pattern is the text of the regular expression.

Optional flags

i
ignore case

g
global match

gi
global match and ignore case

Description

The literal notation, for example, /ab+c/, provides compilation of the regular expression once when the expression is evaluated. Use literal notation when the regular expression will remain constant. For example, if you use literal notation to construct a regular expression used in a loop, the regular expression won't be recompiled on each interation.

The constructor of the regular expression object, for example, new RegExp("ab+c"), provides runtime compilation of the regular expression. Use the constructor function when you know the regular expression pattern will be changing, or you don't know the pattern and are getting it from another source, such as user input. Once you have a defined regular expression, and if the regular expression is used throughout the script and may change, you can use the compile method to compile a new regular expression for efficient reuse.

Note that when using the constructor function, the normal string escape rules (preceding special characters with \ when included in a string) are necessary. For example, new RegExp("\\w+") is the runtime equivalent of /\w+/. (The special pattern \w+ looks for a match of an alphanumeric character one or more times.)

Property Summary

global
Whether or not to test the regular expression against all possible matches in a string, or only against the first.

ignoreCase
Whether or not to ignore case while attempting a match in a string.

lastIndex
The index at which to start the next match.

source
The text of the pattern.

Method Summary

compile
Compiles a regular expression object.

exec
Executes a search for a match in its string parameter. Returns a result array.

test
Tests for a match in its string parameter. Returns true or false.

Properties

global

A read-only Boolean property that reflects whether or not the "g" flag is used with the regular expression: true if used, false if not used. The "g" flag indicates that the regular expression should be tested against all possible matches in a string.

You cannot change this property directly. However, calling the compile method changes the value of this property.

ignoreCase

A read-only Boolean property that reflects whether or not the "i" flag is used with the regular expression: true if used, false if not used. The "i" flag indicates that case should be ignored while attempting a match in a string.

You cannot change this property directly. However, calling the compile method changes the value of this property.

lastIndex

A read/write integer property that specifies the index at which to start the next match. This property is set only if the regular expression used the "g" flag to indicate a global search. The following rules apply:

For example, consider the following sequence of statements:

re = /(hi)?/g
// Matches the empty string.
re("hi")
// Returns ["hi", "hi"] with lastIndex equal to 2.
re("hi")
// Returns [""], an empty array whose zeroth element is the match
// string. In this case, the empty string because lastIndex was 2 (and
// still is 2) and "hi" has length 2.

source

A property that contains the text of the pattern, excluding the forward slashes and "g" or "i" flags.

You cannot change this property directly. However, calling the compile method changes the value of this property.

Methods

compile

Core method. Compiles a regular expression object during execution of a script.

Syntax

regexp.compile("pattern", ["i"|"g"|"gi"])

Parameters

regexp is the name of the regular expression.

pattern is the text of the regular expression.

Optional flags

i
ignore case

g
global match

gi
global match and ignore case

Description

Use the compile method to compile a regular expression created with the constructor function. This forces compilation of the regular expression once only which means the regular expression isn't compiled each time it is encountered. Use the compile method when you know the regular expression will remain constant (after getting its pattern) and will be used repeatedly throughout the script.

You can also use the compile method to change the regular expression during execution. For example, if the regular expression changes, you can use the compile method to recompile the object for more efficient repeated use.

Calling this method changes the value of the regular expression's source, global, and ignoreCase properties.

exec

Core method. Executes the search for a match in a specified string.

Syntax

regexp.exec(str)
or use the shortcut version

regexp(str)

Parameters

regexp is the name of the regular expression. It can be a variable name or a literal.

str is the string against which to match the regular expression. This is an optional argument. If omitted, the value of RegExp.input is used, as described in Chapter 11, "The RegExp Object."

Description

If you are executing a match simply to find true or false, use the test method or the String search method. If the match succeeds, the exec method returns an array and updates properties of the regular expression object and the predefined regular expression object, RegExp. If the match fails, the exec method returns null.

Consider the following example:

<SCRIPT LANGUAGE="JavaScript1.2">
//Match one d followed by one or more b's followed by one d
//Remember matched b's and the following d
//Ignore case
myRe=/d(b+)(d)/ig;
myArray = myRe.exec("cdbBdbsbz");
</SCRIPT>
The following table shows the results for this script:

Object Property/Index Description Example
myArray
The contents of myArray

["dbBd", "bB", "d"]

index
The 0-based index of the match in the string

1

input
The original string

cdbBdbsbz

[0]
The last matched characters

dbBd

[1], ...[n]
The parenthesized substring matches, if any. The number of possible parenthesized substrings is unlimited.

[1] = bB
[2] = d

myRe
lastIndex
The index at which to start the next match.

5

ignoreCase
Indicates if the "i" flag was used to ignore case

true

global
Indicates if the "g" flag was used for a global match

true

source
The text of the pattern

d(b+)(d)

RegExp
lastMatch 1  
$&
The last matched characters

dbBd

leftContext  
$\Q
The substring preceding the most recent match

c

rightContext  
$'
The substring following the most recent match

bsbz

$1, ...$9
The parenthesized substring matches, if any. The number of possible parenthesized substrings is unlimited, but RegExp can only hold the last nine.

$1 = bB 
$2 = d

lastParen  
$+
The last parenthesized substring match, if any.

d

1 Note that several of the RegExp properties have both long and short (Perl-like) names. Both names always refer to the same value. Perl is the programming language from which JavaScript modeled its regular expressions.

If your regular expression uses the "g" flag, you can use the exec method multiple times to find successive matches in the same string. When you do so, the search starts at the substring of str specified by the regular expression's lastIndex property. For example, assume you have this script:

<SCRIPT LANGUAGE="JavaScript1.2">
myRe=/ab*/g;
str = "abbcdefabh"
myArray = myRe.exec(str);
document.writeln("Found " + myArray[0] +
   ". Next match starts at " + myRe.lastIndex)
mySecondArray = myRe.exec(str);
document.writeln("Found " + mySecondArray[0] +
   ". Next match starts at " + myRe.lastIndex)
</SCRIPT>
This script displays the following text:

Found abb. Next match starts at 3
Found ab. Next match starts at 9

Examples

In the following example, the user enters a name and the script executes a match against the input. It then cycles through the array to see if other names match the user's name.

This script assumes that first names of registered party attendees are preloaded into the array A, perhaps by gathering them from a party database.

<HTML>
<SCRIPT LANGUAGE="JavaScript1.2">
A = ["Frank", "Emily", "Jane", "Harry", "Nick", "Beth", "Rick", \
     "Terrence", "Carol", "Ann", "Terry", "Frank", "Alice", "Rick", \
     "Bill", "Tom", "Fiona", "Jane", "William", "Joan", "Beth"]
re = /\w+/i
function lookup() { 
  firstName = re.exec() 
  if (!firstName) 
     window.alert (RegExp.input + " isn't a name!") 
  else {
     count = 0 
  for (i=0; i<A.length; i++) 
     if (firstName[0].toLowerCase() == A[i].toLowerCase()) 
         count++ 
  if (count ==1) 
     midstring = " other has " 
  else 
     midstring = " others have " 
  window.alert ("Thanks, " + count + midstring + "the same name!") 
  }
}
</SCRIPT>
Enter your first name and then press Enter.
<FORM> <INPUT TYPE:"TEXT" NAME="FirstName" onChange="lookup(this);"> </FORM>
</HTML>

test

Core method. Executes the search for a match between a regular expression and a specified string.

Syntax

regexp.test(str)

Parameters

regexp is the name of the regular expression.

str is the string against which to match the regular expression. This is an optional argument. If omitted, the value of RegExp.input is used, as described in Chapter 11, "The RegExp Object."

Description

When you want to know whether a pattern is found in a string use the test method (similar to the String search method); for more information (but slower execution) use the exec method (similar to the String match method).

Example

The following example prints a message which depends on the success of the test.

function testinput(re, str){
   if (re.test(str))
      midstring = " contains ";
   else 
      midstring = " does not contain ";
   document.write (str + midstring + re.source);
}


[Contents] [Previous] [Next] [Last]

Last Updated: 10/22/97 11:48:15


Copyright © 1997 Netscape Communications Corporation