string.match

The match() method retrieves the matches when matching a string against a regular expression.

Syntax

str.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). If you don't give any parameter and use the match() method directly, you will get an Array with an empty string:[""].

Return value

An Array containing the entire match result and any parentheses-captured matched results; null if there were no matches.

Description

If the regular expression does not include the g flag, str.match() will return the same result as RegExp.exec(). The returned Array has an extra input property, which contains the original string that was parsed. 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 matched substrings rather than match objects. Captured groups are not returned. If there were no matches, the method returns null.

See also: RegExp methods

• If you need to know if a string matches a regular expression RegExp, use search().
• If you only want the first match found, you might want to use RegExp.exec() instead.
• if you want to obtain capture groups and the global flag is set, you need to use RegExp.exec() instead.

Examples

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 upper/lower case differences will be ignored.

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

console.log(found);

// logs [ 'see Chapter 3.4.5.1',
//        'Chapter 3.4.5.1',
//        '.1',
//        index: 22,
//        input: 'For more information, see Chapter 3.4.5.1' ]

// 'see Chapter 3.4.5.1' is the whole match.
// 'Chapter 3.4.5.1' was captured by '(chapter \d+(\.\d)*)'.
// '.1' was the last value captured by '(\.\d)'.
// The 'index' property (22) is the zero-based index of the whole match.
// The 'input' property is the original string that was parsed.

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

console.log(matches_array);
// ['A', 'B', 'C', 'D', 'E', 'a', 'b', 'c', 'd', 'e']

Using match() with no parameter

var str = "Nothing will come of nothing.";

str.match();   // returns [""]

A non-RegExp object as the parameter

When the parameter is a string or a number, it is implicitly converted to a RegExp by using new RegExp(obj). If it is a positive number with a positive sign,the RegExp() method will ignore the positive sign.

var str1 = "NaN means not a number. Infinity contains -Infinity and +Infinity in JavaScript.",
    str2 = "My grandfather is 65 years old and My grandmother is 63 years old.",
    str3 = "The contract was declared null and void.";
str1.match("number");   // "number" is a string. returns ["number"]
str1.match(NaN);        // the type of NaN is the number. returns ["NaN"]
str1.match(Infinity);   // the type of Infinity is the number. returns ["Infinity"]
str1.match(+Infinity);  // returns ["Infinity"]
str1.match(-Infinity);  // returns ["-Infinity"]
str2.match(65);         // returns ["65"]
str2.match(+65);        // A number with a positive sign. returns ["65"]
str3.match(null);       // returns ["null"]

Specifications

Specification	Status	Comment
ECMAScript 3rd Edition (ECMA-262)	Standard	Initial definition. Implemented in JavaScript 1.2.
ECMAScript 5.1 (ECMA-262) The definition of 'String.prototype.match' in that specification.	Standard
ECMAScript 2015 (6th Edition, ECMA-262) The definition of 'String.prototype.match' in that specification.	Standard
ECMAScript 2017 Draft (ECMA-262) The definition of 'String.prototype.match' in that specification.	Draft

Browser compatibility

Firefox-specific notes

• Starting with Gecko 27 (Firefox 27 / Thunderbird 27 / SeaMonkey 2.24), this method has been adjusted to conform with the ECMAScript specification. When match() is called with a global regular expression, the RegExp.lastIndex property (if specified) will be reset to 0 (bug 501739).
• Starting with Gecko 39 (Firefox 39 / Thunderbird 39 / SeaMonkey 2.36), the non-standard flags argument is deprecated and throws a console warning (bug 1142351).
• Starting with Gecko 47 (Firefox 47 / Thunderbird 47 / SeaMonkey 2.44), the non-standard flags argument is no longer supported in non-release builds and will soon be removed entirely (bug 1245801).
• Starting with Gecko 49 (Firefox 49 / Thunderbird 49 / SeaMonkey 2.46), the non-standard flags argument is no longer supported (bug 1108382).

See also

• RegExp
• RegExp.prototype.exec()
• RegExp.prototype.test()