String.prototype.match()

  • Revision slug: JavaScript/Reference/Global_Objects/String/match
  • Revision title: String.match
  • Revision id: 339079
  • Created:
  • Creator: ethertank
  • Is current revision? No
  • Comment

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

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).

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.

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.

{{gecko_callout_heading("8.0")}}

Prior to Gecko 8.0 {{geckoRelease("8.0")}}, match() was implemented incorrectly; when it was called with no parameters or with undefined, it would match against undefined, instead of always returning an empty string. This is fixed.

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>string</em>.match(<em>regexp</em>)</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>.</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>

<p>The returned <a href="/en-US/docs/JavaScript/Reference/Global_Objects/Array" title="JavaScript/Reference/Global_Objects/Array"><code>Array</code></a> has an extra <code>input</code> property, which contains the regexp that generated it as a result. In addition, it has an <code>index</code> property, which represents the zero-based index of the match in the string.</p>

<div class="geckoVersionNote">
  <div>
    {{gecko_callout_heading("8.0")}}</div>
  <p>Prior to Gecko 8.0 {{geckoRelease("8.0")}}, <code>match()</code> was implemented incorrectly; when it was called with no parameters or with <code>undefined</code>, it would match against undefined, instead of always returning an empty string. This is fixed.</p>
</div>
<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