This section describes the regular expression object and its methods.
Regular Expression Object
compile method
exec method
test method
Core object. A regular expression object contains the pattern of a regular expression. (This is not to be confused with the single global object, RegExp.)
Note: The literal text format is compiled into a compact and efficient internal representation.
regexp = /pattern/[i|g|gi]
regexp = new RegExp("pattern", ['i'|'g'|'gi'])
regexp is the name of the regular expression object.
pattern is the text of the regular expression.
| i | ignore case |
| g | global match |
| gi | global match and ignore case |
The literal notation, e.g. /ab+c/, provides compilation of the regular expression once only, when the script is first loaded. 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, e.g. 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, you can use the compile method to compile the 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.)
| 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. |
| 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. |
| lastIndex | A read/write integer property that specifies the index at which to
start the next match. The following rules apply:
For example: re = /(hi)?/g //matches empty string
re("hi") //returns ["hi", "hi"] with
//lastIndex == 2
re("hi") //returns [""], an empty array whose
//[0] 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 read-only property that contains the text of the pattern. |
| 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. |
Core method. Compiles a regular expression object during execution of a script.
regexp.compile("pattern", ['i'|'g'|'gi'])
regexp is the name of the regular expression.
pattern is the text of the regular expression.
| i | ignore case |
| g | global match |
| gi | global match and ignore case |
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.
Core method. Executes the search for a match in a specified string.
regexp.exec(str)
or use the shortcut version
regexp(str)
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.
Note: If you are executing a match simply to find true or false, use the test method or the String search method.
To explain the exec method, look at the following example and then refer to the table below:
<SCRIPT> //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)/i;
myArray = myRe.exec("cdbBdbsbz");
</SCRIPT>
If the match succeeds, the exec method returns an array and updates properties of the regular expression object and the global regular expression object, RegExp, as follows (the examples are the result of the above script):
| Object | Property/Index | Description | Example |
| myArray | the contents of myArray | dbBd,bB,d | |
| index | the zero-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 | false | |
| source | the text of the pattern | d(b+)d | |
| RegExp | lastMatch * $& |
the last matched characters | dbBd |
| leftContext $` |
the string up to the most recent match | c | |
| rightContext $' |
the string past 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 | |
| * Note that four 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 the match fails, the exec method returns null (which converts to Boolean false).
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>
Core method. Executes the search for a match between a regular expression and a specified string.
regexp.test(str)
regexp is the name of the regular expression.
str is the string against which to match the regular expression.
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).
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);
}