ES2020 contains a new String.prototype.matchAll method, which returns an iterator. I'm sure I'm missing something dumb/obvious, but I don't see why it doesn't just return an array instead.

Can someone please explain the logic there?

EDIT: Just to clarify something from the ments, I'm operating on the assumption that iterators haven't simply replaced arrays as the new way all JS APIs going forward will return multiple values. If I missed that memo, and all new JS functions do return iterators, a link to said memo would 100% qualify as a valid answer.

But again, I suspect that such a blanket change wasn't made, and that the makers of Javascript made a specific choice, for this specific method, to have it return an iterator ... and the logic of that choice is what I'm trying to understand.

ES2020 contains a new String.prototype.matchAll method, which returns an iterator. I'm sure I'm missing something dumb/obvious, but I don't see why it doesn't just return an array instead.

Can someone please explain the logic there?

EDIT: Just to clarify something from the ments, I'm operating on the assumption that iterators haven't simply replaced arrays as the new way all JS APIs going forward will return multiple values. If I missed that memo, and all new JS functions do return iterators, a link to said memo would 100% qualify as a valid answer.

But again, I suspect that such a blanket change wasn't made, and that the makers of Javascript made a specific choice, for this specific method, to have it return an iterator ... and the logic of that choice is what I'm trying to understand.

• javascript
• regex
• ecmascript-2020

• i guess it's an replacement of exec, which we used to use instead of matchAll to get the same functionality, since with g flag in match you won't be able to get all the matches as you can get in exec to mimic same functionality it is proposed. – Code Maniac Commented Apr 12, 2020 at 15:58
• But exec returns an Array, not an iterator. From the MDN: "The exec() method executes a search for a match in a specified string. Returns a result array, or null." – machineghost Commented Apr 12, 2020 at 15:59
• it's not like normal array it keeps track of lastindex of match and on next iteration it searches from there, the array holds value of current match and capture group. – Code Maniac Commented Apr 12, 2020 at 16:01
• If the match succeeds, the exec() method returns an array (with extra properties index and input; see below) and updates the lastIndex property of the regular expression object. MDN – Code Maniac Commented Apr 12, 2020 at 16:04
• 1 If you return an array the plete result has to be known when the function call finished. Returning an iterator allows the evaluation of the next result at the time when it is requested. Depending on the use-case this can have benefits for memory and/or responsivnes. – t.niese Commented Apr 12, 2020 at 16:08

1 Answer 1

This is described in the proposal document:

Many use cases may want an array of matches - however, clearly not all will. Particularly large numbers of capturing groups, or large strings, might have performance implications to always gather all of them into an array. By returning an iterator, it can trivially be collected into an array with the spread operator or Array.from if the caller wishes to, but it need not.

.matchAll is lazy. When using the iterator, the regex will only evaluate the next match in the string once the prior match has been iterated over. This means that if the regex is expensive, the first few matches can be extracted, and then your JS logic can make the iterator bail out of trying further matches.

For a trivial example of the lazy evaluation in action:

for (const match of 'axxxxxxxxxxxxxxxxxxxxxxxxxxxxy'.matchAll(/a|(x+x+)+y./g)) {
  if (match[0] === 'a') {
    console.log('Breaking out');
    break;
  }
}
console.log('done');

Without the break, the regular expression will go on to attempt a 2nd match, which will result in a very expensive operation.

If matchAll returned an array, and iterated over all matches immediately while creating the array, it would not be possible to bail out.