Revision 479585 of String.prototype.match()

  • Revision slug: Web/JavaScript/Reference/Global_Objects/String/match
  • Revision title: String.match
  • Revision id: 479585
  • Created:
  • Creator: madarche
  • Is current revision? No
  • Comment Removed the note about ol' Gecko 8

Revision Content

Summary

Used to retrieve the matches when matching a string against a regular expression.

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

Syntax

var array = string.match(regexp);

Parameters

regexp
A regular expression object. If a non-RegExp object obj is passed, it is implicitly converted to a RegExp by using new RegExp(obj).

Description

If the regular expression does not include the g flag, returns the same result as regexp.exec(string). The returned Array has an extra input property, which contains the regexp that generated it as a result. In addition, it has an index property, which represents the zero-based index of the match in the string.

If the regular expression includes the g flag, the method returns an Array containing all matches. If there were no matches, the method returns null.

Notes

  • If you need to know if a string matches a regular expression regexp, use regexp.test(string).
  • If you only want the first match found, you might want to use regexp.exec(string) instead.
  • See §15.5.4.10 of the ECMA-262 specification.

Examples

Example: Using match

In the following example, match is used to find "Chapter" followed by 1 or more numeric characters followed by a decimal point and numeric character 0 or more times. The regular expression includes the i flag so that case will be ignored.

var str = "For more information, see Chapter 3.4.5.1";
var re = /(chapter \d+(\.\d)*)/i;
var found = str.match(re);

alert(found);

This returns the array containing Chapter 3.4.5.1,Chapter 3.4.5.1,.1

"Chapter 3.4.5.1" is the first match and the first value remembered from (Chapter \d+(\.\d)*).

".1" is the second value remembered from (\.\d).

Example: Using global and ignore case flags with match

The following example demonstrates the use of the global and ignore case flags with match. All letters A through E and a through e are returned, each its own element in the array

var str = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var regexp = /[A-E]/gi;
var matches_array = str.match(regexp);

alert(matches_array);

matches_array now equals ['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']

Revision Source

<h2 id="Summary" name="Summary">Summary</h2>
<p>Used to retrieve the matches when matching a <code><em>string</em></code> against a <em>regular expression</em>.</p>
<table class="standard-table">
  <thead>
    <tr>
      <th class="header" colspan="2">Method of <a href="/en-US/docs/JavaScript/Reference/Global_Objects/String" title="JavaScript/Reference/Global_Objects/String"><code>String</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 class="brush: js">var </em><em class="brush: js">array = string</em>.match(regexp);</code></pre>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<dl>
  <dt>
    <code>regexp</code></dt>
  <dd>
    A <a href="/en-US/docs/JavaScript/Reference/Global_Objects/RegExp" title="JavaScript/Reference/Global Objects/RegExp">regular expression</a> object. If a non-RegExp object <code>obj</code> is passed, it is implicitly converted to a RegExp by using <code>new RegExp(obj)</code>.</dd>
</dl>
<h2 id="Description" name="Description">Description</h2>
<p>If the regular expression does not include the <code>g</code> flag, returns the same result as <a href="/en-US/docs/JavaScript/Reference/Global_Objects/RegExp/exec" title="JavaScript/Reference/Global_Objects/RegExp/exec"><code><em>regexp</em>.exec(<em>string</em>)</code></a>. <span style="line-height: 1.572;">The returned&nbsp;</span><a href="/en-US/docs/JavaScript/Reference/Global_Objects/Array" style="line-height: 1.572;" title="JavaScript/Reference/Global_Objects/Array"><code style="font-size: 14px;">Array</code></a><span style="line-height: 1.572;">&nbsp;has an extra&nbsp;</span><code style="font-size: 14px;">input</code><span style="line-height: 1.572;">&nbsp;property, which contains the regexp that generated it as a result. In addition, it has an&nbsp;</span><code style="font-size: 14px;">index</code><span style="line-height: 1.572;">&nbsp;property, which represents the zero-based index of the match in the string.</span></p>
<p>If the regular expression includes the <code>g</code> flag, the method returns an <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Array" title="JavaScript/Reference/Global_Objects/Array"><code>Array</code></a> containing all matches. If there were no matches, the method returns <code>null</code>.</p>
<h3 id="Notes" name="Notes">Notes</h3>
<ul>
  <li>If you need to know if a string matches a regular expression <code>regexp</code>, use <a href="/en-US/docs/JavaScript/Reference/Global_Objects/RegExp/test" title="JavaScript/Reference/Global_Objects/RegExp/test"><code><em>regexp</em>.test(<em>string</em>)</code></a>.</li>
  <li>If you only want the first match found, you might want to use <a href="/en-US/docs/JavaScript/Reference/Global_Objects/RegExp/exec" title="JavaScript/Reference/Global_Objects/RegExp/exec"><code><em>regexp</em>.exec(<em>string</em>)</code></a> instead.</li>
  <li>See §15.5.4.10 of the ECMA-262 specification.</li>
</ul>
<h2 id="Examples" name="Examples">Examples</h2>
<h3 id="Example:_Using_match" name="Example:_Using_match">Example: Using <code>match</code></h3>
<p>In the following example, <code>match</code> is used to find "<code>Chapter</code>" followed by 1 or more numeric characters followed by a decimal point and numeric character 0 or more times. The regular expression includes the <code>i</code> flag so that case will be ignored.</p>
<pre class="brush:js">
var str = "For more information, see Chapter 3.4.5.1";
var re = /(chapter \d+(\.\d)*)/i;
var found = str.match(re);

alert(found);
</pre>
<p>This returns the array containing Chapter 3.4.5.1,Chapter 3.4.5.1,.1</p>
<p>"<code>Chapter 3.4.5.1</code>" is the first match and the first value remembered from <code>(Chapter \d+(\.\d)*)</code>.</p>
<p>"<code>.1</code>" is the second value remembered from <code>(\.\d)</code>.</p>
<h3 id="Example:_Using_global_and_ignore_case_flags_with_match" name="Example:_Using_global_and_ignore_case_flags_with_match">Example: Using global and ignore case flags with <code>match</code></h3>
<p>The following example demonstrates the use of the global and ignore case flags with <code>match</code>. All letters A through E and a through e are returned, each its own element in the array</p>
<pre class="brush:js">
var str = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var regexp = /[A-E]/gi;
var matches_array = str.match(regexp);

alert(matches_array);
</pre>
<p><code>matches_array</code> now equals <code>['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']</code></p>
Revert to this revision