Skip to content
This repository has been archived by the owner on Jan 26, 2022. It is now read-only.

Latest commit

 

History

History
172 lines (150 loc) · 8.67 KB

spec.md

File metadata and controls

172 lines (150 loc) · 8.67 KB
Raw

String.prototype.matchAll ( regexp )

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:

  1. Let O be ? RequireObjectCoercible(this value).
  2. If regexp is neither undefined nor null, then 1. Let matcher be ? [GetMethod][getmethod](regexp, @@matchAll). 1. If matcher is not undefined, then
    1. Return ? Call(matcher, regexp, « O »).
  3. Let S be ? [ToString]tostring.
  4. Let rx be ? RegExpCreate(regexp, "g").
  5. 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.

RegExp.prototype[ @@matchAll ] ( string )

When the @@matchAll method is called with argument string, the following steps are taken:

  1. Let R be the this value.
  2. If Type(R) is not Object, throw a TypeError exception.
  3. Let S be ? [ToString]tostring.
  4. Let C be ? SpeciesConstructor(R, %RegExp%).
  5. Let flags be ? [ToString][tostring](? [Get][get](R, "flags")).
  6. Let matcher be ? Construct(C, « R, flags »).
  7. Let lastIndex be ? ToLength(? [Get][get](R, "lastIndex")).
  8. Perform ? Set(matcher, "lastIndex", lastIndex, true).
  9. If flags contains "g", let global be true.
  10. Else, let global be false.
  11. If flags contains "u", let fullUnicode be true.
  12. Else, let fullUnicode be false.
  13. Return ! CreateRegExpStringIterator(matcher, S, global, fullUnicode).

The value of the name property of this function is "[Symbol.matchAll]".

CreateRegExpStringIterator( R, S, global, fullUnicode )

The abstract operation CreateRegExpStringIterator is used to create such iterator objects. It performs the following steps:

  1. Assert: Type(S) is String.
  2. Assert: Type(global) is Boolean.
  3. Assert: Type(unicode) is Boolean.
  4. Let iterator be ObjectCreate(%RegExpStringIteratorPrototype%, « [[IteratedString]], [[IteratingRegExp]], [[Global]], [[Unicode]], [[Done]] »).
  5. Set iterator.[[IteratingRegExp]] to R.
  6. Set iterator.[[IteratedString]] to S.
  7. Set iterator.[[Global]] to global.
  8. Set iterator.[[Unicode]] to fullUnicode.
  9. Set iterator.[[Done]] to true.
  10. Return iterator.

The %RegExpStringIteratorPrototype% Object

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:

%RegExpStringIteratorPrototype%.next ( )

  1. Let O be the this value.
  2. If Type(O) is not Object, throw a TypeError exception.
  3. If O does not have all of the internal slots of a RegExp String Iterator Object Instance (see here), throw a TypeError exception.
  4. If O.[[Done]] is true, then 1. Return ! CreateIterResultObject(undefined, true).
  5. Let R be O.[[IteratingRegExp]].
  6. Let S be O.[[IteratedString]].
  7. Let global be O.[[Global]].
  8. Let fullUnicode be O.[[Unicode]].
  9. Let match be ? RegExpExec(R, S).
  10. If match is null, then 1. Set O.[[Done]] to true. 1. Return ! CreateIterResultObject(undefined, true).
  11. Else, 1. If global is true,
    1. Let matchStr be ? ToString(? [Get][get](match, "0")).
    2. If matchStr is the empty string,
    3. Let thisIndex be ? ToLength(? [Get][get](R, "lastIndex").
    4. Let nextIndex be ! AdvanceStringIndex(S, thisIndex, fullUnicode).
    5. Perform ? Set(R, "lastIndex", nextIndex, true).
    6. Return ! CreateIterResultObject(match, false). 1. Else,
    7. Set O.[[Done]] to true.
    8. Return ! CreateIterResultObject(match, false).

%RegExpStringIteratorPrototype%[ @@toStringTag ]

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 }.

Properties of RegExp String Iterator Instances

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 Instances
Internal 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.

Symbol.matchAll

The initial value of Symbol.matchAll is the well-known symbol @@matchAll

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false }.

Well-Known Symbols

Table 1: Well-known Symbols
Specification 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