Stage 1 Draft / September 5, 2023

Pattern Matching

6 ECMAScript Data Types and Values

6.1 ECMAScript Language Types

6.1.5 The Symbol Type

6.1.5.1 Well-Known Symbols

Table 1: Well-known Symbols
Specification Name [[Description]] Value and Purpose
@@matcher "Symbol.matcher" A method that performs custom pattern matching semantics. Called by the semantics of the match expression.

7 Misc

7.1 CreateMatchRecord ( matched [ , value ] )

The abstract operation CreateMatchRecord takes argument matched (a Boolean) and optional argument value (an ECMAScript language value) and returns a Match Record. It performs the following steps when called:

  1. If matched is true, then
    1. Assert: value is present.
    2. Return Match Record { [[Matched]]: true, [[Value]]: value }.
  2. Assert: value is not present.
  3. Return Match Record { [[Matched]]: matched, [[Value]]: unused }.

7.2 CreateMatchResultObject ( matched [ , value ] )

The abstract operation CreateMatchResultObject takes argument matched (a Boolean) and optional argument value (an ECMAScript language value) and returns an Object that conforms to the MatchResult interface. It performs the following steps when called:

  1. Let obj be OrdinaryObjectCreate(%Object.prototype%).
  2. Perform ! CreateDataPropertyOrThrow(obj, "matched", matched).
  3. If matched is true, then
    1. Assert: value is present.
    2. Perform ! CreateDataPropertyOrThrow(obj, "value", value).
  4. Else,
    1. Assert: value is not present.
  5. Return obj.

7.3 MatchConstructorInstance ( value, target [ , intrinsicName ] )

The abstract operation MatchConstructorInstance takes arguments value (an Object) and target (an ECMAScript language value) and optional argument intrinsicName (a String) and returns either a normal completion containing an Object that conforms to the MatchResult interface, or an abrupt completion. It performs the following steps when called:

  1. Let O be value.
  2. Repeat,
    1. Let C be ? Get(O, "constructor").
    2. If intrinsicName is present, and C matches the intrinsic described in Table 6 by intrinsicName in any realm, then
      1. Return CreateMatchResultObject(true, value).
    3. If IsConstructor(target) is true, and SameValue(C, target) is true, then
      1. Return CreateMatchResultObject(true, value).
    4. Set O to ? O.[[GetPrototypeOf]]().
    5. If O is null, return CreateMatchResultObject(false).

13 ECMAScript Language: Expressions

13.5 Match Expression

13.5.1 Syntax

Editor's Note
Work in progress.
 MatchExpression :: match [no LineTerminator here] ( Expression ) [no LineTerminator here] { MatchClausesopt } MatchClauses : MatchClause MatchClauses MatchClause MatchClause : when ( MatchPattern ) if ( Expression ) : Expression when ( MatchPattern ) : Expression if ( Expression ) : Expression default : Expression MatchPattern : CombinedMatchPattern InterpolationPattern IdentifierMatchPattern NearLiteralMatchPattern ObjectMatchPattern ArrayMatchPattern ( MatchPattern ) CombinedMatchPattern : MatchPattern or MatchPattern MatchPattern and MatchPattern InterpolationPattern : ${ Expression } with MatchPattern ${ Expression } IdentifierMatchPattern : Identifier NearLiteralMatchPattern : NullLiteral BooleanLiteral NumericLiteral StringLiteral RegularExpressionLiteral with MatchPattern RegularExpressionLiteral TemplateLiteral[~Tagged] + NumericLiteral - NumericLiteral + Infinity - Infinity + NaN - NaN ObjectMatchPattern : { } { MatchRestProperty } { MatchPropertyList } { MatchPropertyList , MatchRestPropertyopt } ArrayMatchPattern : [ Elisionopt MatchRestElementopt ] [ MatchElementList ] [ MatchElementList , Elisionopt MatchRestElementopt ] MatchRestProperty : ... IdentifierMatchPattern MatchPropertyList : MatchProperty MatchPropertyList , MatchProperty MatchElementList : MatchElisionElement MatchElementList , MatchElisionElement MatchElisionElement : Elisionopt MatchPattern MatchProperty : IdentifierMatchPattern PropertyName : MatchPattern MatchRestElement : ... MatchPatternopt Note 1
undefined, NaN, and Infinity are covered by the IdentifierMatchPattern, but +NaN, -NaN, +Infinity, and -Infinity are covered by the NearLiteralMatchPattern.
Note 2
No Initializer is allowed in the current syntax. See https://github.com/tc39/proposal-pattern-matching/#default-values

13.5.2 Static Semantics: Early Errors

Editor's Note
This section has not written in normative spec language yet.
 MatchClauses : MatchClause MatchClauses MatchClause
  • It is a Syntax Error if there are more than one default : clause.
  • It is a Syntax Error if any other clauses follow the default : clause.
NearLiteralMatchPattern : RegularExpressionLiteral with MatchPattern MatchPattern : CombinedMatchPattern
  • It is a Syntax Error if the combined match pattern has both or and and at the same level without a (). For example, a or b and c is an early error, a or (b and c) or (a or b) and c is okay.

13.5.3 Runtime Semantics: Evaluation

MatchExpression :: match ( Expression ) { MatchClausesopt }
  1. Let matchableRef be ? Evaluation of Expression.
  2. Let matchable be ? GetValue(matchableRef).
  3. If MatchClauses is not present, throw a TypeError exception.
  4. Let cacheGroup be ! Construct(%Map%, a new empty List).
  5. Let iterators be ! Construct(%Set%, a new empty List).
  6. Perform ! CreateDataPropertyOrThrow(cacheGroup, "IteratorToClose", iterators).
  7. Let result be Completion(MatchClausesEvaluation of MatchClauses with argument matchable and cacheGroup).
  8. Let iteratorRecords be a new empty List.
  9. For each element iter of iterators.[[SetData]], do
    1. Append iter.[[CachedIterator]] to iteratorRecords.
  10. Perform ? CloseIterators(iteratorRecords).
  11. ReturnIfAbrupt(result).
  12. If result.[[Matched]] is true, return result.[[Value]].
  13. Throw a TypeError exception.
 Note
The object cacheGroup is not accessible from user code. An implementation may choose to avoid the actual creation of the object.

13.5.4 Runtime Semantics: MatchClausesEvaluation

The syntax-directed operation MatchClausesEvaluation takes arguments matchable (an ECMAScript language value) and cacheGroup (a %Map%) and returns either a normal completion containing a Boolean or an abrupt completion. It is defined piecewise over the following productions:

MatchClauses : MatchClause
  1. Return ? MatchClauseEvaluation of MatchClause with argument matchable and cacheGroup.
 MatchClauses : MatchClauses MatchClause
  1. Let result be ? MatchClausesEvaluation of MatchClauses with argument matchable and cacheGroup.
  2. If result.[[Matched]] is true, return result.
  3. Return ? MatchClauseEvaluation of MatchClause with argument matchable and cacheGroup.

13.5.5 Runtime Semantics: MatchClauseEvaluation

The syntax-directed operation MatchClauseEvaluation takes arguments matchable (an ECMAScript language value) and cacheGroup (a %Map%) and returns either a normal completion containing a Match Record or an abrupt completion. It is defined piecewise over the following productions:

MatchClause : when ( MatchPattern ) if ( Expression ) : Expression
  1. Let closure be a new Abstract Closure with parameters () that captures matchable, cacheGroup, MatchPattern, the first Expression, and the second Expression and performs the following steps when called:
    1. Let matches be ? MatchPatternMatches of MatchPattern with arguments matchable and cacheGroup.
    2. If matches is false, return CreateMatchRecord(false).
    3. Let ifRef be ? Evaluation of the first Expression.
    4. Let ifVal be ToBoolean(? GetValue(ifRef)).
    5. If ifVal is false, return CreateMatchRecord(false).
    6. Let exprRef be ? Evaluation of the second Expression.
    7. Let exprVal be ? GetValue(exprRef).
    8. Return CreateMatchRecord(true, exprVal).
  2. Let oldEnv be the running execution context's LexicalEnvironment.
  3. Let matchEnv be NewDeclarativeEnvironment(oldEnv).
  4. Set the running execution context's LexicalEnvironment to matchEnv.
  5. Let result be closure ().
  6. Set the running execution context's LexicalEnvironment to oldEnv.
  7. Return result.
 MatchClause : when ( MatchPattern ) : Expression
  1. Let closure be a new Abstract Closure with parameters () that captures matchable, cacheGroup, MatchPattern, and Expression and performs the following steps when called:
    1. Let matches be ? MatchPatternMatches of MatchPattern with arguments matchable and cacheGroup.
    2. If matches is false, return CreateMatchRecord(false).
    3. Let exprRef be ? Evaluation of Expression.
    4. Let exprVal be ? GetValue(exprRef).
    5. Return CreateMatchRecord(true, exprVal).
  2. Let oldEnv be the running execution context's LexicalEnvironment.
  3. Let matchEnv be NewDeclarativeEnvironment(oldEnv).
  4. Set the running execution context's LexicalEnvironment to matchEnv.
  5. Let result be closure ().
  6. Set the running execution context's LexicalEnvironment to oldEnv.
  7. Return result.
 MatchClause : if ( Expression ) : Expression
  1. Let ifRef be ? Evaluation of the first Expression.
  2. Let ifVal be ToBoolean(? GetValue(ifRef)).
  3. If ifVal is false, return CreateMatchRecord(false).
  4. Let exprRef be ? Evaluation of the second Expression.
  5. Let exprVal be ? GetValue(exprRef).
  6. Return CreateMatchRecord(true, exprVal).
 MatchClause : default : Expression
  1. Let exprRef be ? Evaluation of Expression.
  2. Let exprVal be ? GetValue(exprRef).
  3. Return CreateMatchRecord(true, exprVal).

13.5.6 Runtime Semantics: MatchPatternMatches

The syntax-directed operation MatchPatternMatches takes arguments matchable (an ECMAScript language value) and cacheGroup (a %Map%) and returns either a normal completion containing a Boolean or an abrupt completion. It is defined piecewise over the following productions:

MatchPattern : CombinedMatchPattern
  1. Return ? CombinedMatchPatternMatches of CombinedMatchPattern with arguments matchable and cacheGroup.
 MatchPattern : InterpolationPattern
  1. Return ? InterpolationPatternMatches of InterpolationPattern with arguments matchable and cacheGroup.
 MatchPattern : IdentifierMatchPattern
  1. Let identifier be the Identifier that is covered by IdentifierMatchPattern.
  2. Let name be the StringValue of identifier.
  3. If name is "Infinity", return SameValue(matchable, Infinity).
  4. If name is "undefined", return SameValue(matchable, undefined).
  5. If name is "NaN", return SameValue(matchable, NaN).
  6. Perform AddMatchBinding(name[0], matchable).
  7. Return true.
 MatchPattern : NearLiteralMatchPattern
  1. Return ? NearLiteralMatchPatternMatches of NearLiteralMatchPattern with arguments matchable and cacheGroup.
 MatchPattern : ObjectMatchPattern
  1. Return ? DestructuringMatchPatternMatches of ObjectMatchPattern with arguments matchable and cacheGroup.
 MatchPattern : ArrayMatchPattern
  1. Return ? DestructuringMatchPatternMatches of ArrayMatchPattern with arguments matchable and cacheGroup.
 MatchPattern : ( MatchPattern )
  1. Return ? MatchPatternMatches of MatchPattern with argument matchable and cacheGroup.

13.5.7 Runtime Semantics: CombinedMatchPatternMatches

The syntax-directed operation CombinedMatchPatternMatches takes arguments matchable (an ECMAScript language value) and cacheGroup (a %Map%) and returns either a normal completion containing a Boolean or an abrupt completion. It is defined piecewise over the following productions:

CombinedMatchPattern : MatchPattern or MatchPattern
  1. Let leftMatches be ? MatchPatternMatches of the first MatchPattern with arguments matchable and cacheGroup.
  2. If leftMatches is true, return true.
  3. Return ? MatchPatternMatches of the second MatchPattern with arguments matchable and cacheGroup.
 CombinedMatchPattern : MatchPattern and MatchPattern
  1. Let leftMatches be ? MatchPatternMatches of the first MatchPattern with arguments matchable and cacheGroup.
  2. If leftMatches is false, return false.
  3. Return ? MatchPatternMatches of the second MatchPattern with arguments matchable and cacheGroup.

13.5.8 Runtime Semantics: InterpolationPatternMatches

The syntax-directed operation InterpolationPatternMatches takes arguments matchable (an ECMAScript language value) and cacheGroup (a %Map%) and returns either a normal completion containing a Boolean or an abrupt completion. It is defined piecewise over the following productions:

InterpolationPattern : ${ Expression }
  1. Let exprRef be ? Evaluation of Expression.
  2. Let exprVal be ? GetValue(exprRef).
  3. Let result be ? InvokeCustomMatcher(exprVal, matchable).
  4. If result is not-matched, return false.
  5. Return true.
 InterpolationPattern : ${ Expression } with MatchPattern
  1. Let exprRef be ? Evaluation of Expression.
  2. Let exprVal be ? GetValue(exprRef).
  3. Let result be ? InvokeCustomMatcher(exprVal, matchable).
  4. If result is not-matched, return false.
  5. Return ? MatchPatternMatches of MatchPattern with arguments result and cacheGroup.

13.5.9 Runtime Semantics: NearLiteralMatchPatternMatches

The syntax-directed operation NearLiteralMatchPatternMatches takes arguments matchable (an ECMAScript language value) and cacheGroup (a %Map%) and returns either a normal completion containing a Boolean or an abrupt completion. It is defined piecewise over the following productions:

NearLiteralMatchPattern : NullLiteral
  1. Return SameValue(matchable, null).
 NearLiteralMatchPattern : BooleanLiteral
  1. Return SameValue(matchable, ? Evaluation of BooleanLiteral).
 NearLiteralMatchPattern : NumericLiteral
  1. Let numeric be ? Evaluation of NumericLiteral.
  2. NOTE: TODO: -0𝔽 is handled already, but when there is no explicit + sign, the next line should use SameValueZero.
  3. Return SameValue(matchable, numeric).
 NearLiteralMatchPattern : StringLiteral
  1. Return SameValue(matchable, ? Evaluation of StringLiteral).
 NearLiteralMatchPattern : RegularExpressionLiteral with MatchPattern
  1. Let regexp be ? Evaluation of RegularExpressionLiteral.
  2. Let result be ? RegExpBuiltinExec(regexp, ? ToString(matchable)).
  3. If result is null, return false.
  4. Perform RegularExpressionNamedCaptureGroupBindingInitialization(result).
  5. Return ? MatchPatternMatches of MatchPattern with arguments result and cacheGroup.
 NearLiteralMatchPattern : RegularExpressionLiteral
  1. Let regexp be ? Evaluation of RegularExpressionLiteral.
  2. Let result be ? RegExpBuiltinExec(regexp, ? ToString(matchable)).
  3. If result is null, return false.
  4. Perform RegularExpressionNamedCaptureGroupBindingInitialization(result).
  5. Return true.
 Note
The object that returned from RegExpBuiltinExec in this Abstract Operation is not accessible from user code. An implementation may choose to avoid the actual creation of the object.
NearLiteralMatchPattern : TemplateLiteral[~Tagged]
  1. Let strRef be ? Evaluation of TemplateLiteral.
  2. Let str be ? GetValue(strRef).
  3. Return SameValue(matchable, str).
 NearLiteralMatchPattern : + NumericLiteral
  1. Let num be ? Evaluation of NumericLiteral.
  2. Return SameValueZero(matchable, num).
 NearLiteralMatchPattern : - NumericLiteral
  1. Let num be ? Evaluation of NumericLiteral.
  2. Return SameValueZero(matchable, -num).
 NearLiteralMatchPattern : + Infinity
  1. Return SameValue(matchable, Infinity).
 NearLiteralMatchPattern : - Infinity
  1. Return SameValue(matchable, -Infinity).
 NearLiteralMatchPattern : + NaN NearLiteralMatchPattern : - NaN
  1. Return SameValue(matchable, NaN).

13.5.10 Runtime Semantics: DestructuringMatchPatternMatches

The syntax-directed operation DestructuringMatchPatternMatches takes arguments matchable (an ECMAScript language value) and cacheGroup (a %Map%) and returns either a normal completion containing a Boolean or an abrupt completion. It is defined piecewise over the following productions:

ObjectMatchPattern : { }
  1. If Type(matchable) is not Object, return false.
  2. Return true.
 ObjectMatchPattern : { MatchRestProperty }
  1. Let restObj be OrdinaryObjectCreate(%Object.prototype%).
  2. Let excludedNames be a new empty List.
  3. Perform ? CopyDataProperties(restObj, matchable, excludedNames).
  4. Perform ? MatchRestPropertyEvaluation of MatchRestProperty with arguments restObj, cacheGroup and excludedNames.
  5. Return true.
 ObjectMatchPattern : { MatchPropertyList }
  1. If Type(matchable) is not Object, return false.
  2. Let result be ? MatchPropertyEvaluation of MatchPropertyList with arguments matchable and cacheGroup.
  3. If result is a List, return true.
  4. Return false.
 ObjectMatchPattern : { MatchPropertyList , MatchRestPropertyopt }
  1. If Type(matchable) is not Object, return false.
  2. Let result be ? MatchPropertyEvaluation of MatchPropertyList with arguments matchable and cacheGroup.
  3. If result is not-matched, return false.
  4. Assert: result is a List.
  5. Let excludedNames be result.
  6. If MatchRestProperty is present, then
    1. Let restObj be OrdinaryObjectCreate(%Object.prototype%).
    2. Perform ? CopyDataProperties(restObj, matchable, excludedNames).
    3. Return ? MatchRestPropertyEvaluation of MatchRestProperty with arguments restObj, cacheGroup and excludedNames.
  7. Return result.
 ArrayMatchPattern : [ Elisionopt MatchRestElementopt ]
  1. If ? MatchCachedIsIterable(cacheGroup, matchable) is false, return false.
  2. Let index be Record { [[LastIndex]]: -1 }.
  3. If Elision is present, then
    1. Let result be ? MatchElementEvaluation of Elision with arguments matchable, cacheGroup and index.
    2. If result is false, return false.
  4. If MatchRestElement is present, then
    1. Return ? MatchElementEvaluation of MatchRestElement with arguments matchable, cacheGroup and index.
  5. Return ? MatchIteratorLengthMatch(cacheGroup, matchable, index.[[LastIndex]]).
 ArrayMatchPattern : [ MatchElementList ]
  1. If ? MatchCachedIsIterable(cacheGroup, matchable) is false, return false.
  2. Let index be Record { [[LastIndex]]: -1 }.
  3. Let result be ? MatchElementEvaluation of MatchElementList with arguments matchable, cacheGroup and index.
  4. If result is false, return false.
  5. Return ? MatchIteratorLengthMatch(cacheGroup, matchable, index.[[LastIndex]]).
 ArrayMatchPattern : [ MatchElementList , Elisionopt MatchRestElementopt ]
  1. If ? MatchCachedIsIterable(cacheGroup, matchable) is false, return false.
  2. Let index be Record { [[LastIndex]]: -1 }.
  3. Let result be ? MatchElementEvaluation of MatchElementList with arguments matchable, cacheGroup and index.
  4. If result is false, return false.
  5. If Elision is present, then
    1. Let result2 be ? MatchElementEvaluation of Elision with arguments matchable, cacheGroup and index.
    2. If result2 is false, return false.
  6. If MatchRestElement is present, then
    1. Return ? MatchElementEvaluation of MatchRestElement with arguments matchable, cacheGroup and index.
  7. Return ? MatchIteratorLengthMatch(cacheGroup, matchable, index.[[LastIndex]]).

13.5.11 Runtime Semantics: MatchPropertyEvaluation

The syntax-directed operation MatchPropertyEvaluation takes arguments matchable (an ECMAScript language value) and cacheGroup (a %Map%) and returns either a normal completion containing either not-matched or a List, or a throw completion. It is defined piecewise over the following productions:

MatchPropertyList : MatchProperty
  1. Return ? MatchPropertyEvaluation of MatchProperty with arguments matchable and cacheGroup.
 MatchPropertyList : MatchPropertyList , MatchProperty
  1. Let result be ? MatchPropertyEvaluation of MatchPropertyList with arguments matchable and cacheGroup.
  2. If result is not-matched, return false.
  3. Let result2 be ? MatchPropertyEvaluation of MatchProperty with arguments matchable and cacheGroup.
  4. If result2 is not-matched, return false.
  5. Return the list-concatenation of result and result2.
 MatchProperty : IdentifierMatchPattern
  1. Let identifier be the Identifier that is covered by IdentifierMatchPattern.
  2. Let name be the StringValue of identifier.
  3. If ? MatchCachedHasProperty(cacheGroup, matchable, name) is false, return false.
  4. Let value be ? MatchCachedGet(cacheGroup, matchable, name).
  5. Perform AddMatchBinding(name, value).
  6. Return true.
 MatchProperty : PropertyName : MatchPattern
  1. Let propKey be ? Evaluation of PropertyName.
  2. ReturnIfAbrupt(propKey).
  3. If ? MatchCachedHasProperty(cacheGroup, matchable, propKey) is false, return false.
  4. Let value be ? MatchCachedGet(cacheGroup, matchable, propKey).
  5. Return ? MatchPatternMatches of MatchPattern with arguments value and cacheGroup.

13.5.12 Runtime Semantics: MatchRestPropertyEvaluation

The syntax-directed operation MatchRestPropertyEvaluation takes arguments matchable (an ECMAScript language value), cacheGroup (a %Map%), and excludedNames (a List) and returns either a normal completion containing unused or an abrupt completion. It is defined piecewise over the following productions:

MatchRestProperty : ... IdentifierMatchPattern
  1. Let identifier be the Identifier that is covered by IdentifierMatchPattern.
  2. Let name be the StringValue of identifier.
  3. Let rest be OrdinaryObjectCreate(%Object.prototype%).
  4. Perform ? CopyDataProperties(rest, matchable, excludedNames).
  5. Perform AddMatchBinding(name, _rest).
  6. Return unused.

13.5.13 Runtime Semantics: MatchElementEvaluation

The syntax-directed operation MatchElementEvaluation takes arguments matchable (an ECMAScript language value), cacheGroup (a %Map%), and counter (a Record) and returns either a normal completion containing a Boolean or an abrupt completion. It is defined piecewise over the following productions:

MatchRestElement : ... MatchPatternopt
  1. If MatchPattern is not present, return true.
  2. Let iteratorRecord be ? MatchCachedGetIterator(cacheGroup, matchable).
  3. Let A be ! ArrayCreate(0).
  4. Let n be 0.
  5. Repeat,
    1. Let next be ? MatchCachedIteratorStep(cacheGroup, iteratorRecord).
    2. If iteratorRecord.[[Matched]] is false, then
      1. Return ? MatchPatternMatches of MatchPattern with arguments A and cacheGroup.
    3. Perform ! CreateDataPropertyOrThrow(A, ! ToString(𝔽(n)), next.[[Value]]).
    4. Set n to n + 1.
 MatchElementList : MatchElisionElement
  1. Return ? MatchElementEvaluation of MatchElisionElement with arguments matchable, cacheGroup, and counter.
 MatchElementList : MatchElementList , MatchElisionElement
  1. Let result be ? MatchElementEvaluation of MatchElementList with arguments matchable, cacheGroup, and counter.
  2. If result is false, return false.
  3. Return ? MatchElementEvaluation of MatchElisionElement with arguments matchable, cacheGroup, and counter.
 MatchElisionElement : Elisionopt MatchPattern
  1. If Elision is present, then
    1. Let result be ? MatchElementEvaluation of Elision with arguments matchable, cacheGroup, and counter.
    2. If result is false, return false.
  2. Let value be ? MatchCachedGetIteratorNthItem(cacheGroup, matchable, counter.[[LastIndex]]).
  3. If value.[[Matched]] is false, return false.
  4. Let result2 be ? MatchPatternMatches of MatchPattern with arguments value.[[Value]] and cacheGroup.
  5. If result2 is false, return false.
  6. Set counter.[[LastIndex]] to counter.[[LastIndex]] + 1.
  7. Return true.
 Elision : ,
  1. Let result be ? MatchCachedGetIteratorNthItem(cacheGroup, matchable, counter.[[LastIndex]]).
  2. If result.[[Matched]] is false, return false.
  3. Set counter.[[LastIndex]] to counter.[[LastIndex]] + 1.
  4. Return true.
 Elision : Elision ,
  1. Let result be ? MatchElementEvaluation of Elision with arguments matchable, cacheGroup, and counter.
  2. If result is false, return false.
  3. Let result2 be ? MatchCachedGetIteratorNthItem(cacheGroup, matchable, counter.[[LastIndex]]).
  4. If result2.[[Matched]] is false, return false.
  5. Set counter.[[LastIndex]] to counter.[[LastIndex]] + 1.
  6. Return true.

13.5.14 Match Records

A Match Record is a Record value used to represent the match result of the match clause.

Match Record have the fields listed in Table 1.

Table 2: Table 1
Field NameValueMeaning
[[Matched]]a BooleanIf the match clause matched.
[[Value]]an ECMAScript language value or unusedThe matched value.

13.5.15 InvokeCustomMatcher ( val, matchable )

The abstract operation InvokeCustomMatcher takes arguments val (an ECMAScript language value) and matchable (an ECMAScript language value) and returns either a normal completion containing either an ECMAScript language value or not-matched, or an abrupt completion. It performs the following steps when called:

  1. If Type(val) is not Object, then
    1. If SameValueZero(val, matchable), return val.
    2. Return not-matched.
  2. Let matcher be ? Get(val, @@matcher).
  3. If IsCallable(matcher) is false, throw a TypeError exception.
  4. Let result be ? Call(matcher, val, « matchable »).
  5. If Type(result) is Boolean, then
    1. If result is false, return not-matched.
    2. Return val.
  6. If Type(result) is not Object, throw a TypeError exception.
  7. Let matched be ToBoolean(? Get(result, "matched")).
  8. If matched is false, return not-matched.
  9. Return ? Get(result, "value").

13.5.16 RegularExpressionNamedCaptureGroupBindingInitialization ( regexMatchResult )

The abstract operation RegularExpressionNamedCaptureGroupBindingInitialization takes argument regexMatchResult (an Array) and returns unused. It performs the following steps when called:

  1. Let groups be ! Get(regexMatchResult, "groups").
  2. If groups is undefined, return.
  3. Let bindings be ! GetOwnPropertyKeys(groups, String).
  4. Let oldEnv be the running execution context's LexicalEnvironment.
  5. Let matchEnv be NewDeclarativeEnvironment(oldEnv).
  6. Set the running execution context's LexicalEnvironment to matchEnv.
  7. For each element name of bindings, do
    1. Perform ! matchEnv.CreateImmutableBinding(name, true).
    2. Perform ! matchEnv.InitializeBinding(name, ! Get(groups, name)).
 Note
The object regexMatchResult that is used in this Abstract Operation is not accessible from user code. An implementation may choose to avoid the actual creation of the object.

13.5.17 GetMatchCache ( cacheGroup, object )

The abstract operation GetMatchCache takes arguments cacheGroup (a Map) and object (an ECMAScript language value) and returns an ECMAScript language value. It performs the following steps when called:

  1. If ! Call(%Map.prototype.has%, cacheGroup, « object ») is true, then
    1. Return ! Call(%Map.prototype.get%, cacheGroup, « object »).
  2. Let cache be OrdinaryObjectCreate(null).
  3. Perform ! CreateDataPropertyOrThrow(cache, "Has", ! Construct(%Set%, undefined, a new empty List)).
  4. Perform ! CreateDataPropertyOrThrow(cache, "Get", ! Construct(%Map%, undefined, a new empty List)).
  5. Perform ! CreateDataPropertyOrThrow(cache, "Iterator", undefined).
  6. Perform ! CreateDataPropertyOrThrow(cache, "IteratedItems", ! ArrayCreate(0)).
  7. Perform ! Call(%Map.prototype.set%, cacheGroup, « object, cache »).
  8. Return cache.
 Note
The object cache and all of its data properties are not accessible from user code. An implementation may choose to avoid the actual creation of the object.

13.5.18 MatchCachedHasProperty ( cacheGroup, object, propertyName )

The abstract operation MatchCachedHasProperty takes arguments cacheGroup (a Map), object (an ECMAScript language value), and propertyName (a property key) and returns either a normal completion containing a Boolean or an abrupt completion. It performs the following steps when called:

  1. Let cache be ! Get(GetMatchCache(cacheGroup, object), "Has").
  2. Let cachedResult be ! Call(%Map.prototype.get%, cache, « propertyName »).
  3. If Type(cachedResult) is Boolean, return cachedResult.
  4. Let result be ? HasProperty(object, propertyName).
  5. Perform ! Call(%Map.prototype.set%, cache, « propertyName, result »).
  6. Return result.

13.5.19 MatchCachedGet ( cacheGroup, object, propertyName )

The abstract operation MatchCachedGet takes arguments cacheGroup (a Map), object (an ECMAScript language value), and propertyName (a property key) and returns either a normal completion containing an ECMAScript language value or an abrupt completion. It performs the following steps when called:

  1. Let cache be ! Get(GetMatchCache(cacheGroup, object), "Get").
  2. Let hasCache be ! Call(%Map.prototype.has%, cache, « propertyName »).
  3. If hasCache is true, return ! Call(%Map.prototype.get%, cache, « propertyName »).
  4. Let result be ? Get(object, propertyName).
  5. Perform ! Call(%Map.prototype.set%, cache, « propertyName, result »).
  6. Return result.

13.5.20 MatchCachedIsIterable ( cacheGroup, object )

The abstract operation MatchCachedIsIterable takes arguments cacheGroup (a Map) and object (an ECMAScript language value) and returns either a normal completion containing a Boolean or an abrupt completion. It performs the following steps when called:

  1. Let iter be ? MatchCachedGet(cacheGroup, object, @@iterator).
  2. If Type(iter) is not Function, return false.
  3. Return true.

13.5.21 MatchCachedGetIterator ( cacheGroup, object )

The abstract operation MatchCachedGetIterator takes arguments cacheGroup (a Map) and object (an ECMAScript language value) and returns either a normal completion containing an Iterator Record or an abrupt completion. It performs the following steps when called:

  1. Let cache be GetMatchCache(cacheGroup, object).
  2. Let iter be ! Get(cache, "Iterator").
  3. If iter is not undefined, return iter.[[CachedIterator]].
  4. Let f be ? MatchCachedGet(cacheGroup, object, @@iterator).
  5. Set iter to OrdinaryObjectCreate(null, « [[CachedIterator]] »).
  6. Set iter.[[CachedIterator]] to ? GetIteratorFromMethod(object, f).
  7. Perform ! Set(cache, "Iterator", iter, true).
  8. Perform ! Call(%Set.prototype.add%, ! Get(cacheGroup, "IteratorToClose"), « iter »).
  9. Return iter.[[CachedIterator]].

13.5.22 MatchCachedIteratorStep ( cacheGroup, iterator )

The abstract operation MatchCachedIteratorStep takes arguments cacheGroup (a Map) and iterator (an Iterator Record) and returns either a normal completion containing a Match Record or an abrupt completion. It performs the following steps when called:

  1. If iterator.[[Done]] is true, return CreateMatchRecord(false).
  2. Let cache be GetMatchCache(cacheGroup, iterator).
  3. Let cachedItems be ! Get(cache, "IteratedItems").
  4. Let iterResult be Completion(IteratorStep(iterator)).
  5. If iterResult is an abrupt completion, set iterator.[[Done]] to true.
  6. ReturnIfAbrupt(iterResult).
  7. If iterResult is false, then
    1. Set iterator.[[Done]] to true.
    2. Return CreateMatchRecord(false).
  8. Let value be Completion(IteratorValue(iterResult)).
  9. If value is an abrupt completion, set iterator.[[Done]] to true.
  10. ReturnIfAbrupt(value).
  11. Perform ! Call(%Array.prototype.push%, cachedItems, « value »).
  12. Return CreateMatchRecord(true, value).

13.5.23 MatchCachedGetIteratorNthItem ( cacheGroup, iterator, n )

The abstract operation MatchCachedGetIteratorNthItem takes arguments cacheGroup (a Map), iterator (an Iterator Record), and n (a Number) and returns either a normal completion containing a Match Record or an abrupt completion. It performs the following steps when called:

  1. Let cache be GetMatchCache(cacheGroup, iterator).
  2. Let cachedItems be ! Get(cache, "IteratedItems").
  3. Let nthItem be ! cachedItems.[[GetOwnProperty]](n).
  4. If nthItem is not undefined, return CreateMatchRecord(true, nthItem.[[Value]]).
  5. If iterator.[[Done]] is true, return CreateMatchRecord(false).
  6. Return ? MatchCachedIteratorStep(cacheGroup, iterator).

13.5.24 MatchIteratorLengthMatch ( cacheGroup, matchable, lastIndex )

The abstract operation MatchIteratorLengthMatch takes arguments cacheGroup (a Map), matchable (an ECMAScript language value), and lastIndex (a Number) and returns either a normal completion containing a Boolean or an abrupt completion. It performs the following steps when called:

  1. Let iterator be ? MatchCachedGetIterator(cacheGroup, matchable).
  2. Let cache be GetMatchCache(cacheGroup, iterator).
  3. Let cachedItems be ! Get(cache, "IteratedItems").
  4. Let length be ! Get(cachedItems, "length").
  5. If lastIndex > -1, then
    1. If length > lastIndex, return false.
    2. If _iter ator_.[[Done]] is true, then
      1. If length = lastIndex, return true.
      2. Return false.
  6. Let iterResult be ? MatchCachedGetIteratorNthItem(cacheGroup, iterator, lastIndex + 1).
  7. If iterResult.[[Matched]] is true, return false.
  8. Return true.

13.5.25 CloseIterators ( iterators )

The abstract operation CloseIterators takes argument iterators (a List of Iterator Records) and returns either a normal completion containing unused or a throw completion. It performs the following steps when called:

  1. Let errors be a new empty List.
  2. For each element iter of iterators, do
    1. If iter.[[Done]] is false, then
      1. Let completion be Completion(IteratorClose(iter, NormalCompletion(undefined))).
      2. If completion is an abrupt completion, append completion.[[Value]] to errors.
  3. If errors is not empty, then
    1. If length of errors is 1, return ThrowCompletion(errors[0]).
    2. Let error be a newly created AggregateError object.
    3. Perform ! DefinePropertyOrThrow(error, "errors", PropertyDescriptor { [[Configurable]]: true, [[Enumerable]]: false, [[Writable]]: true, [[Value]]: CreateArrayFromList(errors) }).
    4. Return ThrowCompletion(error).
  4. Return unused.

13.5.26 AddMatchBinding ( name, value )

The abstract operation AddMatchBinding takes arguments name (a String) and value (an ECMAScript language value) and returns unused. It performs the following steps when called:

  1. Let oldEnv be the running execution context's LexicalEnvironment.
  2. Let matchEnv be NewDeclarativeEnvironment(oldEnv).
  3. Set the running execution context's LexicalEnvironment to matchEnv.
  4. Perform ! matchEnv.CreateImmutableBinding(name, true).
  5. Perform ! matchEnv.InitializeBinding(name, value).
  6. Return unused.

13.10 Relational Operators

Syntax

RelationalExpression[In, Yield, Await] : ShiftExpression[?Yield, ?Await] RelationalExpression[?In, ?Yield, ?Await] < ShiftExpression[?Yield, ?Await] RelationalExpression[?In, ?Yield, ?Await] > ShiftExpression[?Yield, ?Await] RelationalExpression[?In, ?Yield, ?Await] <= ShiftExpression[?Yield, ?Await] RelationalExpression[?In, ?Yield, ?Await] >= ShiftExpression[?Yield, ?Await] RelationalExpression[?In, ?Yield, ?Await] instanceof ShiftExpression[?Yield, ?Await] RelationalExpression[?In, ?Yield, ?Await] [no LineTerminator here] is MatchPattern[?Yield, ?Await] [+In] RelationalExpression[+In, ?Yield, ?Await] in ShiftExpression[?Yield, ?Await] [+In] PrivateIdentifier in ShiftExpression[?Yield, ?Await]

13.10.1 Runtime Semantics: Evaluation

RelationalExpression : RelationalExpression is MatchPattern[?Yield, ?Await]
  1. Let matchable be ? Evaluation of RelationalExpression.
  2. Let cacheGroup be ! Construct(%Map%, a new empty List).
  3. Let oldEnv be the running execution context's LexicalEnvironment.
  4. Let matchEnv be NewDeclarativeEnvironment(oldEnv).
  5. Set the running execution context's LexicalEnvironment to matchEnv.
  6. Let result be Completion(MatchPatternMatches of MatchPattern with arguments matchable and cacheGroup).
  7. Set the running execution context's LexicalEnvironment to oldEnv.
  8. Return ? result.

20 Fundamental Objects

20.1 Object Objects

20.1.2 Properties of the Object Constructor

20.1.2.23 Object [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is an Object.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, return CreateMatchResultObject(false).
  2. Return CreateMatchResultObject(true, value).

20.2 Function Objects

20.2.2 Properties of the Function Constructor

20.2.2.3 Function [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a Function.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If IsCallable(value) is false, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%Function%").

20.2.3 Properties of the Function Prototype Object

20.2.3.7 Function.prototype [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a Function, or an instance of a class constructor.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Return ? MatchConstructorInstance(value, this value).

20.3 Boolean Objects

20.3.2 Properties of the Boolean Constructor

20.3.2.2 Boolean [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a Boolean.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let result be Completion(thisBooleanValue(value)).
  2. If result is an abrupt completion, return CreateMatchResultObject(false).
  3. Return CreateMatchResultObject(true, result).

20.3.3 Properties of the Boolean Prototype Object

20.3.3.4 Boolean.prototype [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a matching Boolean.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let B be ? thisBooleanValue(this value).
  2. Let result be Completion(thisBooleanValue(value)).
  3. If result is an abrupt completion or SameValue(B, result) is false, return CreateMatchResultObject(false).
  4. Return CreateMatchResultObject(true, result).

20.4 Symbol Objects

20.4.2 Properties of the Symbol Constructor

20.4.2.17 Symbol [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a Symbol.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let result be Completion(thisSymbolValue(value)).
  2. If result is an abrupt completion, return CreateMatchResultObject(false).
  3. Return CreateMatchResultObject(true, result).

20.4.3 Properties of the Symbol Prototype Object

20.4.3.5 Symbol.prototype [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is the same Symbol.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let S be ? thisSymbolValue(this value).
  2. Let result be Completion(thisSymbolValue(value)).
  3. If result is an abrupt completion or SameValue(S, result) is false, return CreateMatchResultObject(false).
  4. Return CreateMatchResultObject(true, result).

20.5 Error Objects

20.5.2 Properties of the Error Constructor

20.5.2.2 Error [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is an Error.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have an [[ErrorData]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%Error%").

20.5.6 NativeError Object Structure

20.5.6.2 Properties of the NativeError Constructors

20.5.6.2.2 NativeError [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a NativeError.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have an [[ErrorData]] internal slot, return CreateMatchResultObject(false).
  2. Let intrinsicName be the string-concatenation of "%", the String value consisting of the name of the constructor (the name used instead of NativeError), and "%".
  3. Return ? MatchConstructorInstance(value, this value, intrinsicName).

20.5.7 AggregateError Objects

20.5.7.1 The AggregateError Constructor

20.5.7.1.1 AggregateError ( errors, message [ , options ] )

When the AggregateError function is called with arguments errors and message and optional argument options, the following steps are taken:

  1. If NewTarget is undefined, let newTarget be the active function object; else let newTarget be NewTarget.
  2. Let O be ? OrdinaryCreateFromConstructor(newTarget, "%AggregateError.prototype%", « [[ErrorData]] »).
  3. If message is not undefined, then
    1. Let msg be ? ToString(message).
    2. Perform CreateNonEnumerableDataPropertyOrThrow(O, "message", msg).
  4. Perform ? InstallErrorCause(O, options).
  5. Let errorsList be ? IteratorToList(? GetIterator(errors, sync)).
  6. Perform ! DefinePropertyOrThrow(O, "errors", PropertyDescriptor { [[Configurable]]: true, [[Enumerable]]: false, [[Writable]]: true, [[Value]]: CreateArrayFromList(errorsList) }).
  7. Return O.

20.5.7.2 Properties of the AggregateError Constructor

20.5.7.2.2 AggregateError [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is an AggregateError.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have an [[ErrorData]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%AggregateError%").

21 Numbers and Dates

21.1 Number Objects

21.1.2 Properties of the Number Constructor

21.1.2.16 Number [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a Number.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let result be Completion(thisNumberValue(value)).
  2. If result is an abrupt completion, return CreateMatchResultObject(false).
  3. Return CreateMatchResultObject(true, result).

21.1.3 Properties of the Number Prototype Object

21.1.3.8 Number.prototype [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is the same Number.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let N be ? thisNumberValue(this value).
  2. Let result be Completion(thisNumberValue(value)).
  3. If result is an abrupt completion or SameValueZero(N, result) is false, return CreateMatchResultObject(false).
  4. Return CreateMatchResultObject(true, result).

21.2 BigInt Objects

21.2.2 Properties of the BigInt Constructor

21.2.2.4 BigInt [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a BigInt.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let result be Completion(thisBigIntValue(value)).
  2. If result is an abrupt completion, return CreateMatchResultObject(false).
  3. Return CreateMatchResultObject(true, result).

21.2.3 Properties of the BigInt Prototype Object

21.2.3.6 BigInt.prototype [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is the same BigInt.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let B be ? thisBigIntValue(this value).
  2. Let result be Completion(thisBigIntValue(value)).
  3. If result is an abrupt completion or SameValue(B, result) is false, return CreateMatchResultObject(false).
  4. Return CreateMatchResultObject(true, result).

21.4 Date Objects

21.4.3 Properties of the Date Constructor

21.4.3.5 Date [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a Date.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have a [[DateValue]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%Date%").

22 Text Processing

22.1 String Objects

22.1.2 Properties of the String Constructor

22.1.2.5 String [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a String.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let result be Completion(thisStringValue(value)).
  2. If result is an abrupt completion, return CreateMatchResultObject(false).
  3. Return CreateMatchResultObject(true, result).

22.1.3 Properties of the String Prototype Object

22.1.3.35 String.prototype [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is the same String.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let S be ? thisStringValue(this value).
  2. Let result be Completion(thisStringValue(value)).
  3. If result is an abrupt completion or SameValue(S, result) is false, return CreateMatchResultObject(false).
  4. Return CreateMatchResultObject(true, result).

22.2 RegExp (Regular Expression) Objects

22.2.4 Properties of the RegExp Constructor

22.2.4.1 RegExp [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a RegExp.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let result be Completion(IsRegExp(value)).
  2. If result is an abrupt completion, or if result.[[Value]] is false, return CreateMatchResultObject(false).
  3. Return ? MatchConstructorInstance(value, this value, "%RegExp%").

22.2.5 Properties of the RegExp Prototype Object

22.2.5.10 RegExp.prototype [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value matches the RegExp.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let R be the this value.
  2. Perform ? RequireInternalSlot(R, [[RegExpMatcher]]).
  3. Let result be ? RegExpBuiltinExec(R, ? ToString(value)).
  4. If result is null, return CreateMatchResultObject(false).
  5. Return CreateMatchResultObject(true, result).

23 Indexed Collections

23.1 Array Objects

23.1.1 Properties of the Array Constructor

23.1.1.6 Array [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is an Array.

When the @@matcher method is called with argument value, the following steps are taken:

  1. Let result be Completion(IsArray(value)).
  2. If result is an abrupt completion, or if result.[[Value]] is false, return CreateMatchResultObject(false).
  3. Return ? MatchConstructorInstance(value, this value, "%Array%").

23.2 TypedArray Objects

23.2.6 Properties of the TypedArray Constructors

23.2.6.3 TypedArray [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a TypedArray.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, return CreateMatchResultObject(false).
  2. If value does not have a [[TypedArrayName]] internal slot, return CreateMatchResultObject(false).
  3. If value.[[TypedArrayName]] is not TypedArray, return CreateMatchResultObject(false).
  4. Let intrinsicName be the string-concatenation of "%", value.[[TypedArrayName]], and "%".
  5. Return ? MatchConstructorInstance(value, this value, intrinsicName).
 Editor's Note
TODO: probably i need to convert TypedArray into a string to be able to do the comparison to the internal slot.

24 Keyed Collections

24.1 Map Objects

24.1.2 Properties of the Map Constructor

24.1.2.3 Map [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a Map.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have a [[MapData]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%Map%").

24.2 Set Objects

24.2.2 Properties of the Set Constructor

24.2.2.3 Set [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a Set.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have a [[SetData]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%Set%").

24.3 WeakMap Objects

24.3.2 Properties of the WeakMap Constructor

24.3.2.2 WeakMap [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a WeakMap.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have a [[WeakMapData]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%WeakMap%").

24.4 WeakSet Objects

24.4.2 Properties of the WeakSet Constructor

24.4.2.2 WeakSet [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a WeakSet.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have a [[WeakSetData]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%WeakSet%").

25 Structured Data

25.1 ArrayBuffer Objects

25.1.4 Properties of the ArrayBuffer Constructor

25.1.4.4 ArrayBuffer [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is an ArrayBuffer.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have an [[ArrayBufferData]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%ArrayBuffer%").

25.2 SharedArrayBuffer Objects

25.2.3 Properties of the SharedArrayBuffer Constructor

25.2.3.3 SharedArrayBuffer [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a SharedArrayBuffer.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have an [[ArrayBufferData]] internal slot, return CreateMatchResultObject(false).
  2. If IsSharedArrayBuffer(value) is false, return CreateMatchResultObject(false).
  3. Return ? MatchConstructorInstance(value, this value, "%SharedArrayBuffer%").

25.3 DataView Objects

25.3.3 Properties of the DataView Constructor

25.3.3.2 DataView [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a DataView.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have a [[DataView]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%DataView%").

26 Managing Memory

26.1 WeakRef Objects

26.1.2 Properties of the WeakRef Constructor

26.1.2.2 WeakRef [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a WeakRef.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have a [[WeakRefTarget]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%WeakRef%").

26.2 FinalizationRegistry Objects

26.2.2 Properties of the FinalizationRegistry Constructor

26.2.2.2 FinalizationRegistry [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a FinalizationRegistry.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If Type(value) is not Object, or if value does not have a [[Cells]] internal slot, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%FinalizationRegistry%").

27 Control Abstraction Objects

27.2 Promise Objects

27.2.4 Properties of the Promise Constructor

27.2.4.9 Promise [ @@matcher ] ( value )

This function is called by ECMAScript pattern matching to determine if the value is a Promise.

When the @@matcher method is called with argument value, the following steps are taken:

  1. If IsPromise(value) is false, return CreateMatchResultObject(false).
  2. Return ? MatchConstructorInstance(value, this value, "%Promise%").
 Editor's Note
TODO: decide if we want to loosen this to accept thenables, breaking with the precedent set here by the rest of the built-in matchers.

1000 TODO

1000.1 Confirm we do not want matchers for these constructors

  1. Iterator/AsyncIterator (probably when Iterator Helpers advances).
  2. Record/Tuple (definintely when R&T advances).
  3. GeneratorFunction/AsyncFunction/AsyncGeneratorFunction (maybe).
  4. Generator/AsyncGenerator (probably not).
  5. Proxy (definitely not).

1000.2 Should we add builtin matchers on the prototype for relevant class instances, so they do something useful?

  1. Date: should compare the time value, and not identity.
  2. RegExp: should compare pattern/flags, and maybe lastIndex?.
  3. Array/Typed Array/Map/Set: should match type, and then iterate and match against contents?.

A Copyright & Software License

Copyright Notice

© 2023 Daniel Rosenwasser,Jack Works,Jordan Harband,Mark Cohen,Ross Kirsling,Tab Atkins

Software License

All Software contained in this document ("Software") is protected by copyright and is being made available under the "BSD License", included below. This Software may be subject to third party rights (rights from parties other than Ecma International), including patent rights, and no licenses under such third party rights are granted under this license even if the third party concerned is a member of Ecma International. SEE THE ECMA CODE OF CONDUCT IN PATENT MATTERS AVAILABLE AT https://ecma-international.org/memento/codeofconduct.htm FOR INFORMATION REGARDING THE LICENSING OF PATENT CLAIMS THAT ARE REQUIRED TO IMPLEMENT ECMA INTERNATIONAL STANDARDS.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
  3. Neither the name of the authors nor Ecma International may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE ECMA INTERNATIONAL "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ECMA INTERNATIONAL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.