Javascript [Electronic resources] : The Definitive Guide (4th Edition) نسخه متنی

Availability

JavaScript 1.2; JScript 3.0; ECMAScript v3

Synopsis

regexp.exec(string)

Arguments

string

The string to be searched.

Returns

An array containing the results of the match, or
null if no match was found. The format of the
returned array is described below.

Throws

TypeError

If this method is invoked on an object that is not a RegExp.

Description

exec( ) is the most powerful of all the RegExp and
String pattern matching methods. It is a general-purpose method that
is somewhat more complex to use than RegExp.test(
), String.search( ),
String.replace( ), and String.match(
).

exec( ) searches string
for text that matches regexp. If it finds
a match, it returns an array of results; otherwise, it returns
null. Element 0 of the returned array is the
matched text. Element 1 is the text that matched the first
parenthesized subexpression, if any, within
regexp. Element 2 contains the text that
matched the second subexpression, and so on. The array
length property specifies the number of elements
in the array, as usual. In addition to the array elements and the
length property, the value returned by
exec( ) also has two other properties. The
index property specifies the character position of
the first character of the matched text. The input
property refers to string. This returned
array is the same as the array that is returned by the
String.match( ) method, when invoked on a
nonglobal RegExp object.

When exec( ) is invoked on a nonglobal pattern, it
performs the search and returns the result described above. When
regexp is a global regular expression,
however, exec( ) behaves in a slightly more
complex way. It begins searching string at
the character position specified by the lastIndex
property of regexp. When it finds a match,
it sets lastIndex to the position of the first
character after the match. This means that you can invoke
exec( ) repeatedly in order to loop through all
matches in a string. When exec( ) cannot find any
more matches, it returns null and resets
lastIndex to zero. If you begin searching a new
string immediately after successfully finding a match in another
string, you must be careful to manually reset
lastIndex to zero.

Note that exec( ) always includes full details of
every match in the array it returns, whether or not
regexp is a global pattern. This is where
exec( ) differs from String.match(
), which returns much less information when used with
global patterns. Calling the exec( ) method
repeatedly in a loop is the only way to obtain complete pattern
matching information for a global pattern.

Example

You can use exec( ) in a loop to find all matches
within a string. For example:

var pattern = /\bJava\w*\b/g;
var text = "JavaScript is more fun than Java or JavaBeans!";
var result;
while((result = pattern.exec(text)) != null) {
alert("Matched `" + result[0] +
"' at position " + result.index +
" next search begins at position " + pattern.lastIndex);
}

Bugs

In JScript 3.0, exec( ) does not properly set or
use the lastIndex property, so it cannot be used
with global patterns in the kind of loop shown in the example above.

See Also

RegExp.lastIndex, RegExp.test( ), String.match( ), String.replace( ),
String.search( ); Chapter 10