mozilla

Revision 359523 of RegExp.prototype.exec()

  • Revision slug: JavaScript/Reference/Global_Objects/RegExp/exec
  • Revision title: RegExp.exec
  • Revision id: 359523
  • Created:
  • Creator: Nickolay
  • Is current revision? No
  • Comment reorganize monolithic "Description" into multiple sections, move a note about an old Gecko bug to the bottom of the page

Revision Content

Summary

Executes a search for a match in a specified string. Returns a result array, or null.

Method of RegExp
Implemented in JavaScript 1.2
ECMAScript Edition ECMAScript 3rd Edition

Syntax

result = regexp.exec(str)

Parameters

regexp
The name of the regular expression. It can be a variable name or a literal.
str
The string against which to match the regular expression.

Return value

If the match succeeds, the exec method returns an array and updates properties of the regular expression object. The returned array has the matched text as the first item, and then one item for each capturing parenthesis that matched containing the text that was captured.

If the match fails, the exec method returns null.

If you are executing a match simply to find true or false, use the RegExp test method or the String search method.

Consider the following example:

// Match one d followed by one or more b's followed by one d
// Remember matched b's and the following d
// Ignore case
var re = /d(b+)(d)/ig;
var result = re.exec("cdbBdbsbz");

The following table shows the results for this script:

Object Property/Index Description Example
result {{mediawiki.external(0)}} The last matched characters dbBd
{{mediawiki.external(1)}}, ...{{mediawiki.external('n')}} The parenthesized substring matches, if any. The number of possible parenthesized substrings is unlimited. {{mediawiki.external(1)}} = bB
{{mediawiki.external(2)}} = d
index The 0-based index of the match in the string. 1
input The original string. cdbBdbsbz
re 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
multiline Indicates if the "m" flag was used to search in strings across multiple line. false
source The text of the pattern. d(b+)(d)

Notes

Finding successive matches

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 (test will also advance the lastIndex property). For example, assume you have this script:

var myRe = /ab*/g;
var str = "abbcdefabh";
var myArray;
while ((myArray = myRe.exec(str)) !== null)
{
  var msg = "Found " + myArray[0] + ".  ";
  msg += "Next match starts at " + myRe.lastIndex;
  console.log(msg);
}

This script displays the following text:

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

Note: Do not place the regular expression literal (or RegExp constructor) within the while condition or it will create an infinite loop if there is a match due to the lastIndex property being reset upon each iteration.

Using exec() with RegExp literals

You can also use exec() without creating a RegExp object:

var matches = /(hello \S+)/.exec('This is a hello world!');
alert(matches[1]);

This will display an alert containing 'hello world!';

Calling exec() with no parameters in old Gecko versions

{{gecko_callout_heading("8.0")}}

Prior to Gecko 8.0 {{geckoRelease("8.0")}}, exec() was implemented incorrectly; when it was called with no parameters, it would match against the value of the previous input (RegExp.input property) instead of against the string "undefined". This is fixed; now /undefined/.exec() correctly results in ['undefined'], instead of an error.

 

Revision Source

<h2 id="Summary" name="Summary">Summary</h2>
<p>Executes a search for a match in a specified string. Returns a result array, or <code>null</code>.</p>
<table class="standard-table">
  <thead>
    <tr>
      <th class="header" colspan="2">Method of <a href="/en-US/docs/JavaScript/Reference/Global_Objects/RegExp" title="JavaScript/Reference/Global_Objects/RegExp"><code>RegExp</code></a></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Implemented in</td>
      <td>JavaScript 1.2</td>
    </tr>
    <tr>
      <td>ECMAScript Edition</td>
      <td>ECMAScript 3rd Edition</td>
    </tr>
  </tbody>
</table>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="syntaxbox">
<code><em>result</em> = <em>regexp</em>.exec(<em>str</em>)</code></pre>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<dl>
  <dt>
    <code>regexp</code></dt>
  <dd>
    The name of the regular expression. It can be a variable name or a literal.</dd>
  <dt>
    <code>str</code></dt>
  <dd>
    The string against which to match the regular expression.</dd>
</dl>
<h3 id="Description" name="Description">Return value</h3>
<p>If the match succeeds, the <code>exec</code> method returns an array and updates properties of the regular expression object. The returned array has the matched text as the first item, and then one item for each capturing parenthesis that matched containing the text that was captured.</p>
<p>If the match fails, the <code>exec</code> method returns <code>null</code>.</p>
<p>If you are executing a match simply to find true or false, use the <code>RegExp</code> <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/RegExp/test" title="JavaScript/Reference/Global_Objects/RegExp/test">test</a></code> method or the <code>String</code> <code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/String/search" title="JavaScript/Reference/Global_Objects/String/search">search</a></code> method.</p>
<p>Consider the following example:</p>
<pre class="brush: js">
// Match one d followed by one or more b's followed by one d
// Remember matched b's and the following d
// Ignore case
var re = /d(b+)(d)/ig;
var result = re.exec("cdbBdbsbz");
</pre>
<p>The following table shows the results for this script:</p>
<table class="fullwidth-table">
  <tbody>
    <tr>
      <td class="header">Object</td>
      <td class="header">Property/Index</td>
      <td class="header">Description</td>
      <td class="header">Example</td>
    </tr>
    <tr>
      <td rowspan="4"><code>result</code></td>
      <td><code>{{mediawiki.external(0)}}</code></td>
      <td>The last matched characters</td>
      <td><code>dbBd</code></td>
    </tr>
    <tr>
      <td><code>{{mediawiki.external(1)}}, ...{{mediawiki.external('<i>n</i>')}}</code></td>
      <td>The parenthesized substring matches, if any. The number of possible parenthesized substrings is unlimited.</td>
      <td><code>{{mediawiki.external(1)}} = bB<br />
        {{mediawiki.external(2)}} = d</code></td>
    </tr>
    <tr>
      <td><code>index</code></td>
      <td>The 0-based index of the match in the string.</td>
      <td><code>1</code></td>
    </tr>
    <tr>
      <td><code>input</code></td>
      <td>The original string.</td>
      <td><code>cdbBdbsbz</code></td>
    </tr>
    <tr>
      <td rowspan="5"><code>re</code></td>
      <td><code>lastIndex</code></td>
      <td>The index at which to start the next match.</td>
      <td><code>5</code></td>
    </tr>
    <tr>
      <td><code>ignoreCase</code></td>
      <td>Indicates if the "<code>i</code>" flag was used to ignore case.</td>
      <td><code>true</code></td>
    </tr>
    <tr>
      <td><code>global</code></td>
      <td>Indicates if the "<code>g</code>" flag was used for a global match.</td>
      <td><code>true</code></td>
    </tr>
    <tr>
      <td><code>multiline</code></td>
      <td>Indicates if the "<code>m</code>" flag was used to search in strings across multiple line.</td>
      <td><code>false</code></td>
    </tr>
    <tr>
      <td><code>source</code></td>
      <td>The text of the pattern.</td>
      <td><code>d(b+)(d)</code></td>
    </tr>
  </tbody>
</table>
<h2>Notes</h2>
<h3>Finding successive matches</h3>
<p>If your regular expression uses the "<code>g</code>" flag, you can use the <code>exec</code> method multiple times to find successive matches in the same string. When you do so, the search starts at the substring of <code>str</code> specified by the regular expression's <code>lastIndex</code> property (<code><a href="/en-US/docs/JavaScript/Reference/Global_Objects/RegExp/test" title="JavaScript/Reference/Global_Objects/RegExp/test">test</a></code> will also advance the <code>lastIndex</code> property). For example, assume you have this script:</p>
<pre class="brush: js">
var myRe = /ab*/g;
var str = "abbcdefabh";
var myArray;
while ((myArray = myRe.exec(str))&nbsp;!== null)
{
  var msg = "Found " + myArray[0] + ".  ";
  msg += "Next match starts at " + myRe.lastIndex;
  console.log(msg);
}
</pre>
<p>This script displays the following text:</p>
<pre>
Found abb. Next match starts at 3
Found ab. Next match starts at 9
</pre>
<p>Note: Do not place the regular expression literal (or <code>RegExp</code> constructor) within the <code>while</code> condition or it will create an infinite loop if there is a match due to the <code>lastIndex</code> property being reset upon each iteration.</p>
<h3>Using exec() with RegExp literals</h3>
<p>You can also use <code>exec()</code> without creating a RegExp object:</p>
<pre class="brush: js">
var matches = /(hello \S+)/.exec('This is a hello world!');
alert(matches[1]);</pre>
<p>This will display an alert containing 'hello world!';</p>
<h3>Calling exec() with no parameters in old Gecko versions</h3>
<div class="geckoVersionNote">
  <p>{{gecko_callout_heading("8.0")}}</p>
  <p>Prior to Gecko 8.0 {{geckoRelease("8.0")}}, <code>exec()</code> was implemented incorrectly; when it was called with no parameters, it would match against the value of the previous input (RegExp.input property) instead of against the string "undefined". This is fixed; now <code>/undefined/.exec()</code> correctly results in <code>['undefined']</code>, instead of an error.</p>
</div>
<p>&nbsp;</p>
Revert to this revision