mozilla

Revision 71321 of String.prototype.match()

  • Revision slug: JavaScript/Reference/Global_Objects/String/match
  • Revision title: match
  • Revision id: 71321
  • Created:
  • Creator: carpetsmoker
  • Is current revision? No
  • Comment Don't use document.write() in examples; 720 words added, 129 words removed

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

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.

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

    Additional Reading

    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.

    <script type="text/javascript">
    str = "For more information, see Chapter 3.4.5.1";
    re = /(chapter \d+(\.\d)*)/i;
    found = str.match(re);
    alert(found);
    </script>
    

    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 {{ mediawiki.external('\'A\', \'B\', \'C\', \'D\', \'E\', \'a\', \'b\', \'c\', \'d\', \'e\'') }}

     

    {{ languages( { "es": "es/Referencia_de_JavaScript_1.5/Objetos_globales/String/match", "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/String/match", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/String/match" } ) }}

          • See §15.5.4.10 of the ECMA-262 specification.
          • See §15.5.4.10 of the ECMA-262 specification.
          • See §15.5.4.10 of the ECMA-262 specification.
          • See §15.5.4.10 of the ECMA-262 specification.
          • See §15.5.4.10 of the ECMA-262 specification.
          • See §15.5.4.10 of the ECMA-262 specification.
          • See §15.5.4.10 of the ECMA-262 specification.
          • See §15.5.4.10 of the ECMA-262 specification.
  • Revision Source

    <h2 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>
    <p> </p>
    <table class="standard-table"> <thead> <tr> <th class="header" colspan="2">Method of <a href="/en/JavaScript/Reference/Global_Objects/String" title="en/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 name="Syntax">Syntax</h2>
    <p><code><em>string</em>.match(<em>regexp</em>)</code></p>
    <h2 name="Parameters">Parameters</h2>
    <h2 name="Description">Description</h2>
    <p>If the regular expression does not include the <code>g</code> flag, returns the same result as <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/exec" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec"><em>regexp</em>.exec(<em>string</em>)</a></code>.</p>
    <p>If the regular expression includes the <code>g</code> flag, the method returns an <code><a href="/en/JavaScript/Reference/Global_Objects/Array" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a></code> containing all matches. If there were no matches, the method returns <code>null</code>.</p>
    <p>The returned <code><a href="/en/JavaScript/Reference/Global_Objects/Array" title="en/Core_JavaScript_1.5_Reference/Global_Objects/Array">Array</a></code> 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>
    <dl> <li> <ul> <li> <ul> <li> <ul> <li> <dl> <dt><code>regexp</code></dt> <dd>A <a href="/en/JavaScript/Reference/Global_Objects/RegExp" title="en/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> </li> </ul> </li> <li> <ul> <li> <dl> <dt><code>regexp</code></dt> <dd>A <a href="/en/JavaScript/Reference/Global_Objects/RegExp" title="en/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> </li> </ul> </li> </ul> </li> <li> <ul> <li> <ul> <li> <dl> <dt><code>regexp</code></dt> <dd>A <a href="/en/JavaScript/Reference/Global_Objects/RegExp" title="en/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> </li> </ul> </li> <li> <ul> <li> <dl> <dt><code>regexp</code></dt> <dd>A <a href="/en/JavaScript/Reference/Global_Objects/RegExp" title="en/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> </li> </ul> </li> </ul> </li> </ul> </li> <li> <ul> <li> <ul> <li> <ul> <li> <dl> <dt><code>regexp</code></dt> <dd>A <a href="/en/JavaScript/Reference/Global_Objects/RegExp" title="en/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> </li> </ul> </li> <li> <ul> <li> <dl> <dt><code>regexp</code></dt> <dd>A <a href="/en/JavaScript/Reference/Global_Objects/RegExp" title="en/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> </li> </ul> </li> </ul> </li> <li> <ul> <li> <ul> <li> <dl> <dt><code>regexp</code></dt> <dd>A <a href="/en/JavaScript/Reference/Global_Objects/RegExp" title="en/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> </li> </ul> </li> <li> <ul> <li> <dl> <dt><code>regexp</code></dt> <dd>A <a href="/en/JavaScript/Reference/Global_Objects/RegExp" title="en/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> </li> </ul> </li> </ul> </li> </ul> </li>
    </dl>
    <div class="geckoVersionNote"> <p>{{ gecko_callout_heading("8.0") }}</p> <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 name="Notes">Notes</h3>
    <h2 name="Additional_Reading">Additional Reading</h2>
    <h2 name="Examples">Examples</h2>
    <h3 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>&lt;script type="text/javascript"&gt;
    str = "For more information, see Chapter 3.4.5.1";
    re = /(chapter \d+(\.\d)*)/i;
    found = str.match(re);
    alert(found);
    &lt;/script&gt;
    </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 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>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>{{ mediawiki.external('\'A\', \'B\', \'C\', \'D\', \'E\', \'a\', \'b\', \'c\', \'d\', \'e\'') }}</code></p>
    <p> </p>
    <p>{{ languages( { "es": "es/Referencia_de_JavaScript_1.5/Objetos_globales/String/match", "ja": "ja/Core_JavaScript_1.5_Reference/Global_Objects/String/match", "pl": "pl/Dokumentacja_j\u0119zyka_JavaScript_1.5/Obiekty/String/match" } ) }}</p>
    <dl> <li> <ul> <li> <ul> <li> <ul> <li> <ul> <li>If you need to know if a string matches a regular expression <code>regexp</code>, use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/test" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/test"><em>regexp</em>.test(<em>string</em>)</a></code>.</li> <li>If you only want the first match found, you might want to use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/exec" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec"><em>regexp</em>.exec(<em>string</em>)</a></code> instead.</li> </ul> <ul> <li>See §15.5.4.10 of the ECMA-262 specification.</li> </ul> </li> </ul> </li> <li> <ul> <li> <ul> <li>If you need to know if a string matches a regular expression <code>regexp</code>, use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/test" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/test"><em>regexp</em>.test(<em>string</em>)</a></code>.</li> <li>If you only want the first match found, you might want to use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/exec" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec"><em>regexp</em>.exec(<em>string</em>)</a></code> instead.</li> </ul> <ul> <li>See §15.5.4.10 of the ECMA-262 specification.</li> </ul> </li> </ul> </li> </ul> </li> <li> <ul> <li> <ul> <li> <ul> <li>If you need to know if a string matches a regular expression <code>regexp</code>, use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/test" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/test"><em>regexp</em>.test(<em>string</em>)</a></code>.</li> <li>If you only want the first match found, you might want to use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/exec" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec"><em>regexp</em>.exec(<em>string</em>)</a></code> instead.</li> </ul> <ul> <li>See §15.5.4.10 of the ECMA-262 specification.</li> </ul> </li> </ul> </li> <li> <ul> <li> <ul> <li>If you need to know if a string matches a regular expression <code>regexp</code>, use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/test" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/test"><em>regexp</em>.test(<em>string</em>)</a></code>.</li> <li>If you only want the first match found, you might want to use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/exec" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec"><em>regexp</em>.exec(<em>string</em>)</a></code> instead.</li> </ul> <ul> <li>See §15.5.4.10 of the ECMA-262 specification.</li> </ul> </li> </ul> </li> </ul> </li> </ul> </li> <li> <ul> <li> <ul> <li> <ul> <li> <ul> <li>If you need to know if a string matches a regular expression <code>regexp</code>, use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/test" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/test"><em>regexp</em>.test(<em>string</em>)</a></code>.</li> <li>If you only want the first match found, you might want to use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/exec" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec"><em>regexp</em>.exec(<em>string</em>)</a></code> instead.</li> </ul> <ul> <li>See §15.5.4.10 of the ECMA-262 specification.</li> </ul> </li> </ul> </li> <li> <ul> <li> <ul> <li>If you need to know if a string matches a regular expression <code>regexp</code>, use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/test" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/test"><em>regexp</em>.test(<em>string</em>)</a></code>.</li> <li>If you only want the first match found, you might want to use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/exec" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec"><em>regexp</em>.exec(<em>string</em>)</a></code> instead.</li> </ul> <ul> <li>See §15.5.4.10 of the ECMA-262 specification.</li> </ul> </li> </ul> </li> </ul> </li> <li> <ul> <li> <ul> <li> <ul> <li>If you need to know if a string matches a regular expression <code>regexp</code>, use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/test" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/test"><em>regexp</em>.test(<em>string</em>)</a></code>.</li> <li>If you only want the first match found, you might want to use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/exec" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec"><em>regexp</em>.exec(<em>string</em>)</a></code> instead.</li> </ul> <ul> <li>See §15.5.4.10 of the ECMA-262 specification.</li> </ul> </li> </ul> </li> <li> <ul> <li> <ul> <li>If you need to know if a string matches a regular expression <code>regexp</code>, use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/test" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/test"><em>regexp</em>.test(<em>string</em>)</a></code>.</li> <li>If you only want the first match found, you might want to use <code><a href="/en/JavaScript/Reference/Global_Objects/RegExp/exec" title="en/Core_JavaScript_1.5_Reference/Global_Objects/RegExp/exec"><em>regexp</em>.exec(<em>string</em>)</a></code> instead.</li> </ul> <ul> <li>See §15.5.4.10 of the ECMA-262 specification.</li> </ul> </li> </ul> </li> </ul> </li> </ul> </li>
    </dl>
    Revert to this revision