mozilla

Revision 70354 of RegExp.prototype.exec()

  • Revision slug: JavaScript/Reference/Global_Objects/RegExp/exec
  • Revision title: exec
  • Revision id: 70354
  • Created:
  • Creator: Ziesemer
  • Is current revision? No
  • Comment /* Description */

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, NES3.0
ECMA Version: ECMA-262, Edition 3 (first syntax only)

Syntax

var result1 = regexp.exec(str);
var result2 = regexp(str); // Mozilla extension

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.

Description

As shown in the syntax description, a regular expression's exec method can be called either directly, (with regexp.exec(str)) or indirectly (with regexp(str)).

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. If the match fails, the exec method returns null.

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 myRe = /d(b+)(d)/ig;
var myArray = myRe.exec("cdbBdbsbz");

The following table shows the results for this script:

Object Property/Index Description Example
myArray   The content of myArray. {{ mediawiki.external('\"dbBd\", \"bB\", \"d\"') }}
index The 0-based index of the match in the string. 1
input The original string. cdbBdbsbz
{{ 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
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
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)

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:

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;
  print(msg);
}

This script displays the following text:

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

Examples

Example: Using exec

In the following example, the function 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.

var A = ["Frank", "Emily", "Jane", "Harry", "Nick", "Beth", "Rick",
         "Terrence", "Carol", "Ann", "Terry", "Frank", "Alice", "Rick",
         "Bill", "Tom", "Fiona", "Jane", "William", "Joan", "Beth"];

function lookup(input)
{
  var firstName = /\w+/i.exec(input);
  if (!firstName)
  {
    print(input + " isn't a name!");
    return;
  }

  var count = 0;
  for (var i = 0; i < A.length; i++)
  {
    if (firstName[0].toLowerCase() == A[i].toLowerCase())
      count++;
  }
  var midstring = count == 1
                ? " other has ";
                : " others have ";
  print("Thanks, " + count + midstring + "the same name!")
}
{{ languages( { "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/RegExp/exec" } ) }}

Revision Source

<p>
</p>
<h3 name="Summary"> Summary </h3>
<p>Executes a search for a match in a specified string. Returns a result array, or <code>null</code>.
</p>
<table class="fullwidth-table">
<tbody><tr>
<td class="header" colspan="2">Method of <a href="en/Core_JavaScript_1.5_Reference/Objects/RegExp">RegExp</a></td>
</tr>
<tr>
<td>Implemented in:</td>
<td>JavaScript 1.2, NES3.0</td>
</tr>
<tr>
<td>ECMA Version:</td>
<td>ECMA-262, Edition 3 (first syntax only)</td>
</tr>
</tbody></table>
<h3 name="Syntax"> Syntax </h3>
<pre class="eval">var result1 = <i>regexp</i>.exec(<i>str</i>);
var result2 = <i>regexp</i>(<i>str</i>); // Mozilla extension
</pre>
<h3 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></dl>
<dl><dt> <code>str</code> </dt><dd> The string against which to match the regular expression.
</dd></dl>
<h3 name="Description"> Description </h3>
<p>As shown in the syntax description, a regular expression's exec method can be called either directly, (with <code>regexp.exec(str)</code>) or indirectly (with <code>regexp(str)</code>).
</p><p>If you are executing a match simply to find true or false, use the <code><a href="en/Core_JavaScript_1.5_Reference/Objects/RegExp/test">test</a></code> method or the <code>String</code> <code><a href="en/Core_JavaScript_1.5_Reference/Objects/String/search">search</a></code> method.
</p><p>If the match succeeds, the <code>exec</code> method returns an array and updates properties of the regular expression object. If the match fails, the <code>exec</code> method returns <code>null</code>.
</p><p>Consider the following example:
</p>
<pre class="eval">// 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 myRe = /d(b+)(d)/ig;
var myArray = myRe.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="5"><code>myArray</code></td>
<td><code> </code></td>
<td>The content of <code>myArray</code>.</td>
<td><code>{{ mediawiki.external('\"dbBd\", \"bB\", \"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><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 rowspan="5"><code>myRe</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>
<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. For example, assume you have this script:
</p>
<pre class="eval">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;
  print(msg);
}
</pre>
<p>This script displays the following text:
</p>
<pre class="eval">Found abb. Next match starts at 3
Found ab. Next match starts at 9
</pre>
<h3 name="Examples"> Examples </h3>
<h4 name="Example:_Using_exec"> Example: Using <code>exec</code> </h4>
<p>In the following example, the function executes a match against the input. It then cycles through the array to see if other names match the user's name.
</p><p>This script assumes that first names of registered party attendees are preloaded into the array <code>A</code>, perhaps by gathering them from a party database.
</p>
<pre class="eval">var A = ["Frank", "Emily", "Jane", "Harry", "Nick", "Beth", "Rick",
         "Terrence", "Carol", "Ann", "Terry", "Frank", "Alice", "Rick",
         "Bill", "Tom", "Fiona", "Jane", "William", "Joan", "Beth"];

function lookup(input)
{
  var firstName = /\w+/i.exec(input);
  if (!firstName)
  {
    print(input + " isn't a name!");
    return;
  }

  var count = 0;
  for (var i = 0; i &lt; A.length; i++)
  {
    if (firstName[0].toLowerCase() == A[i].toLowerCase())
      count++;
  }
  var midstring = count == 1
                ? " other has ";
                : " others have ";
  print("Thanks, " + count + midstring + "the same name!")
}
</pre>{{ languages( { "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/RegExp/exec" } ) }}
Revert to this revision