UNB/ CS/ David Bremner/ teaching/ cs2613/ books/ mdn/ Reference/ Global Objects/ String/ String.prototype.match()

The match() method of String values retrieves the result of matching this string against a regular expression.

Syntax

match(regexp)

Parameters

Return value

An Array whose contents depend on the presence or absence of the global (g) flag, or null if no matches are found.

Description

The implementation of String.prototype.match itself is very simple — it simply calls the Symbol.match method of the argument with the string as the first parameter. The actual implementation comes from RegExp.prototype[@@match]().

For more information about the semantics of match() when a regex is passed, see RegExp.prototype[@@match]().

Examples

Using match()

In the following example, match() is used to find "Chapter" followed by one or more numeric characters followed by a decimal point and numeric character zero or more times.

The regular expression includes the i flag so that upper/lower case differences will be ignored.

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

console.log(found);
// [
//   'see Chapter 3.4.5.1',
//   'Chapter 3.4.5.1',
//   '.1',
//   index: 22,
//   input: 'For more information, see Chapter 3.4.5.1',
//   groups: undefined
// ]

In the match result above, '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 ignoreCase flags with match()

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

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

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

Note: See also String.prototype.matchAll and Advanced searching with flags.

Using named capturing groups

In browsers which support named capturing groups, the following code captures "fox" or "cat" into a group named animal:

const paragraph = "The quick brown fox jumps over the lazy dog. It barked.";

const capturingRegex = /(?<animal>fox|cat) jumps over/;
const found = paragraph.match(capturingRegex);
console.log(found.groups); // {animal: "fox"}

Using match() with no parameter

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

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

Using match() with a non-RegExp implementing @@match

If an object has a Symbol.match method, it can be used as a custom matcher. The return value of Symbol.match becomes the return value of match().

const str = "Hmm, this is interesting.";

str.match({
  [Symbol.match](str) {
    return ["Yes, it's interesting."];
  },
}); // returns ["Yes, it's interesting."]

A non-RegExp as the parameter

When the regexp parameter is a string or a number, it is implicitly converted to a RegExp by using new RegExp(regexp).

const str1 =
  "NaN means not a number. Infinity contains -Infinity and +Infinity in JavaScript.";
const str2 =
  "My grandfather is 65 years old and My grandmother is 63 years old.";
const 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"]

This may have unexpected results if special characters are not properly escaped.

console.log("123".match("1.3")); // [ "123" ]

This is a match because . in a regex matches any character. In order to make it only match specifically a dot character, you need to escape the input.

console.log("123".match("1\\.3")); // null

Specifications

Browser compatibility

See also