Skip to content

Instantly share code, notes, and snippets.

@peterwmwong

peterwmwong/matchAll-spec-to-test.md

Last active March 19, 2018 00:44
Show Gist options
  • Save peterwmwong/2a9d80d3533c0ab165bc8c675ac99e45 to your computer and use it in GitHub Desktop.
Save peterwmwong/2a9d80d3533c0ab165bc8c675ac99e45 to your computer and use it in GitHub Desktop.
Download ZIP
An attempt to map the spec to proposed Test262 test
Raw
matchAll-spec-to-test.md

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. Return ? Call(matcher, regexp, « O »).
  3. Return ? MatchAllIterator(regexp, O).

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. Return ? MatchAllIterator(R, string).

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

MatchAllIterator ( R, O )

The abstract operation MatchAllIterator performs the following steps:

  1. Let S be ? ToString(O).
  2. If ? IsRegExp(R) is true, then
  3. Else, 1. Let matcher be RegExpCreate(R, "g").
  4. Return ! CreateRegExpStringIterator(matcher, S, global, fullUnicode).

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).
    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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment