Performs a regular expression match of the String representing the this value against regexp and returns an iterator. Each iteration result’s value is an Array object containing the results of the match, or null if the String did not match.
When the matchAll
method is called, the following steps are taken:
- Let O be ? RequireObjectCoercible(this value).
- If regexp is neither undefined nor null, then
1. Let matcher be ? [GetMethod][getmethod](regexp, @@matchAll).
1. If matcher is not undefined, then
- Return ? Call(matcher, regexp, « O »).
- Let S be ? [ToString]tostring.
- Let rx be ? RegExpCreate(regexp,
"g"
). - Return ? Invoke(rx, @@matchAll, « S »).
Note 1: The matchAll
function is intentionally generic, it does not require that its this value be a String object. Therefore, it can be transferred to other kinds of objects for use as a method.
Note 2: Similarly to String.prototype.split
, String.prototype.matchAll
is designed to typically act without mutating its inputs.
When the @@matchAll
method is called with argument string, the following steps are taken:
- Let R be the this value.
- If Type(R) is not Object, throw a TypeError exception.
- Let S be ? [ToString]tostring.
- Let C be ? SpeciesConstructor(R, %RegExp%).
- Let flags be ? [ToString][tostring](? [Get][get](R,
"flags"
)). - Let matcher be ? Construct(C, « R, flags »).
- Let lastIndex be ? ToLength(? [Get][get](R,
"lastIndex"
)). - Perform ? Set(matcher, "lastIndex", lastIndex, true).
- If flags contains
"g"
, let global be true. - Else, let global be false.
- If flags contains
"u"
, let fullUnicode be true. - Else, let fullUnicode be false.
- Return ! CreateRegExpStringIterator(matcher, S, global, fullUnicode).
The value of the name property of this function is "[Symbol.matchAll]".
The abstract operation CreateRegExpStringIterator is used to create such iterator objects. It performs the following steps:
- Assert: Type(S) is String.
- Assert: Type(global) is Boolean.
- Assert: Type(unicode) is Boolean.
- Let iterator be ObjectCreate(%RegExpStringIteratorPrototype%, « [[IteratedString]], [[IteratingRegExp]], [[Global]], [[Unicode]], [[Done]] »).
- Set iterator.[[IteratingRegExp]] to R.
- Set iterator.[[IteratedString]] to S.
- Set iterator.[[Global]] to global.
- Set iterator.[[Unicode]] to fullUnicode.
- Set iterator.[[Done]] to true.
- Return iterator.
All RegExp String Iterator Objects inherit properties from the %RegExpStringIteratorPrototype% intrinsic object. The %RegExpStringIteratorPrototype% object is an ordinary object and its [[Prototype]] internal slot is the %IteratorPrototype% intrinsic object. In addition, %RegExpStringIteratorPrototype% has the following properties:
- Let O be the this value.
- If Type(O) is not Object, throw a TypeError exception.
- If O does not have all of the internal slots of a RegExp String Iterator Object Instance (see here), throw a TypeError exception.
- If O.[[Done]] is true, then 1. Return ! CreateIterResultObject(undefined, true).
- Let R be O.[[IteratingRegExp]].
- Let S be O.[[IteratedString]].
- Let global be O.[[Global]].
- Let fullUnicode be O.[[Unicode]].
- Let match be ? RegExpExec(R, S).
- If match is null, then 1. Set O.[[Done]] to true. 1. Return ! CreateIterResultObject(undefined, true).
- Else,
1. If global is true,
- Let matchStr be ? ToString(? [Get][get](match, "0")).
- If matchStr is the empty string,
- Let thisIndex be ? ToLength(? [Get][get](R, "lastIndex").
- Let nextIndex be ! AdvanceStringIndex(S, thisIndex, fullUnicode).
- Perform ? Set(R, "lastIndex", nextIndex, true).
- Return ! CreateIterResultObject(match, false). 1. Else,
- Set O.[[Done]] to true.
- Return ! CreateIterResultObject(match, false).
The initial value of the @@toStringTag property is the String value "RegExp String Iterator".
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.RegExp String Iterator instances are ordinary objects that inherit properties from the %RegExpStringIteratorPrototype% intrinsic object. RegExp String Iterator instances are initially created with the internal slots listed in Table 1.
Table 1 — Internal Slots of RegExp String Iterator InstancesInternal Slot | Description |
---|---|
[[IteratingRegExp]] | The regular expression used for iteration. [IsRegExp][isregexp]([[IteratingRegExp]]) is always initially true. |
[[IteratedString]] | The String value being iterated upon. |
[[Global]] | A Boolean value to indicate whether the [[IteratingRegExp]] is global or not. |
[[Unicode]] | A Boolean value to indicate whether the [[IteratingRegExp]] is in Unicode mode or not. |
[[Done]] | A Boolean value to indicate whether the iteration is complete or not. |
The initial value of Symbol.matchAll is the well-known symbol @@matchAll
This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.
Table 1: Well-known SymbolsSpecification Name | [[Description]] | Value and Purpose |
---|---|---|
insert after @@match | ||
@@matchAll | "Symbol.matchAll" |
A regular expression method that returns an iterator, that yields matches of the regular expression against a string. Called by the String.prototype.matchAll method. |
insert before @@replace |