The matchAll()
method returns an iterator of all results matching a string against a regular expression, including capturing groups.
The matchAll()
method returns an iterator of all results matching a string against a regular expression, including capturing groups.
matchAll(regexp)
regexp
A regular expression object, or any object that has a Symbol.matchAll
method.
If regexp
is not a RegExp
object and does not have a Symbol.matchAll
method, it is implicitly converted to a RegExp
by using new RegExp(regexp, 'g')
.
If regexp
is a regex, then it must have the global (g
) flag set, or a TypeError
is thrown.
An iterable iterator (which is not restartable) of matches. Each match is an array with the same shape as the return value of RegExp.prototype.exec()
.
TypeError
Thrown if the regexp
is a regex that does not have the global (g
) flag set (its flags
property does not contain "g"
).
The implementation of String.prototype.matchAll
itself is very simple — it simply calls the Symbol.matchAll
method of the argument with the string as the first parameter (apart from the extra input validation that the regex is global). The actual implementation comes from RegExp.prototype[@@matchAll]()
.
Without matchAll()
, it's possible to use calls to regexp.exec()
(and regexes with the g
flag) in a loop to obtain all the matches:
const regexp = /foo[a-z]*/g; const str = 'table football, foosball'; let match; while ((match = regexp.exec(str)) !== null) { console.log(`Found ${match[0]} start=${match.index} end=${regexp.lastIndex}.`); // expected output: "Found football start=6 end=14." // expected output: "Found foosball start=16 end=24." }
With matchAll()
available, you can avoid the while
loop and exec
with g
. Instead, you get an iterator to use with the more convenient for...of
, array spreading, or Array.from()
constructs:
const regexp = /foo[a-z]*/g; const str = 'table football, foosball'; const matches = str.matchAll(regexp); for (const match of matches) { console.log(`Found ${match[0]} start=${match.index} end=${match.index + match[0].length}.`); } // expected output: "Found football start=6 end=14." // expected output: "Found foosball start=16 end=24." // matches iterator is exhausted after the for...of iteration // Call matchAll again to create a new iterator Array.from(str.matchAll(regexp), (m) => m[0]); // Array [ "football", "foosball" ]
matchAll
will throw an exception if the g
flag is missing.
const regexp = /[a-c]/; const str = 'abc'; str.matchAll(regexp); // TypeError
matchAll
internally makes a clone of the regexp
— so, unlike regexp.exec()
, lastIndex
does not change as the string is scanned.
const regexp = /[a-c]/g; regexp.lastIndex = 1; const str = 'abc'; Array.from(str.matchAll(regexp), (m) => `${regexp.lastIndex}${m[0]}`); // Array [ "1 b", "1 c" ]
However, this means that unlike using regexp.exec()
in a loop, you can't mutate lastIndex
to make the regex advance or rewind.
Another compelling reason for matchAll
is the improved access to capture groups.
Capture groups are ignored when using match()
with the global g
flag:
const regexp = /t(e)(st(\d?))/g; const str = 'test1test2'; str.match(regexp); // Array ['test1', 'test2']
Using matchAll
, you can access capture groups easily:
const array = [...str.matchAll(regexp)]; array[0]; // ['test1', 'e', 'st1', '1', index: 0, input: 'test1test2', length: 4] array[1]; // ['test2', 'e', 'st2', '2', index: 5, input: 'test1test2', length: 4]
If an object has a Symbol.matchAll
method, it can be used as a custom matcher. The return value of Symbol.matchAll
becomes the return value of matchAll()
.
const str = "Hmm, this is interesting."; str.matchAll({ [Symbol.matchAll](str) { return [["Yes, it's interesting."]]; } }); // returns [["Yes, it's interesting."]]
Desktop | Mobile | Server | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | Deno | Node.js | |
matchAll |
73 |
79 |
67 |
No |
60 |
13 |
73 |
73 |
67 |
52 |
13 |
11.0 |
1.0 |
12.0.0 |
© 2005–2022 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/matchAll