match Method (Windows Scripting - JScript)

Executes a search on a string using a regular expression pattern, and returns an array containing the results of that search.

Syntax

stringObj.match(rgExp) 

Arguments

• stringObj
  Required. The String object or string literal on which to perform the search.

• rgExp
  Required. An instance of a Regular Expression object containing the regular expression pattern and applicable flags. Can also be a variable name or string literal containing the regular expression pattern and flags.

Remarks

If the match method does not find a match, it returns null. If it finds a match, match returns an array, and the properties of the global RegExp object are updated to reflect the results of the match.

The array returned by the match method has three properties, input, index and lastIndex. The input property contains the entire searched string. The index property contains the position of the matched substring within the complete searched string. The lastIndex property contains the position following the last character in the last match.

If the global flag (g) is not set, Element zero of the array contains the entire match, while elements 1 through n contain any submatches that have occurred within the match. This behavior is identical to the behavior of the exec Method (Windows Scripting - JScript) when the global flag is not set. If the global flag is set, elements 0 through n contain all matches that occurred.

Legacy Code Example

The following example illustrates the use of the match method when the global flag (g) is not set.

var src = "Please send mail to george@contoso.com and someone@example.com. Thanks!";

// Create a regular expression to search for an e-mail address.
// The global flag is not included.
// (More sophisticated RegExp patterns are available for
// matching an e-mail address.)
var re = /(\w+)@(\w+)\.(\w+)/;

var result = src.match(re);

// Because the global flag is not included, the entire match is
// in array element 0, and the submatches are in elements 1 through n.
// You can also obtain the submatches from RegExp.$1, RegExp.$2,
// and so on.
for (var index = 0; index < result.length; index++)
{
    if (index > 0)
    {
        document.write ("submatch " + index + ": ");
    }
    document.write(result[index]);
    document.write("<br />");
}

// Output:
//  george@contoso.com
//  submatch 1: george
//  submatch 2: contoso
//  submatch 3: com

The following example illustrates the use of the match method when the global flag (g) is set.

var src = "Please send mail to george@contoso.com and someone@example.com. Thanks!";

// Create a regular expression to search for an e-mail address.
// The global flag is included.
var re = /(\w+)@(\w+)\.(\w+)/g;

var result = src.match(re);

// Because the global flag is included, the matches are in
// array elements 0 through n.
for (var index = 0; index < result.length; index++)
{
    document.write(result[index]);
    document.write("<br />");
}

// Output:
//  george@contoso.com
//  someone@example.com

The following lines of code illustrate the use of a string literal with the match method.

var re = /th/i;
var r = "through the pages of this book".match(re);

Requirements

Version 3

Applies To: String Object (Windows Scripting - JScript)

Change History

See Also

exec Method (Windows Scripting - JScript)
RegExp Object (Windows Scripting - JScript)
Regular Expression Object (Windows Scripting - JScript)
replace Method (Windows Scripting - JScript)
search Method (Windows Scripting - JScript)
test Method (Windows Scripting - JScript)
Regular Expression Programming (Scripting)
Alternation and Subexpressions (Scripting)
Backreferences (Scripting)