Interface PatternMatchers

Matches against the intersection of all sub-Patterns.

Matches any Passable.

Matches any CopyArray, subject to limits.

Matches any CopyArray whose elements are all matched by subPatt if defined, subject to limits.

Matches any CopyBag, subject to limits.

Matches any CopyBag whose elements are all matched by keyPatt if defined and the cardinality of each is matched by countPatt if defined, subject to limits. countPatt is expected to rarely be useful, but is provided to minimize surprise.

Matches any bigint, subject to limits.

Matches true or false.

Matches any ByteArray, subject to limits.

Matches any array, CopySet, or CopyBag in which the bigint number of elements that match elementPatt is >= bound (which defaults to 1n).

Matches any value that is equal to key.

Matches any Passable that is either matched by subPatt or is a promise object. Note that validation is immediate, so (unlike the TypeScript ERef<T> type) M.eref matches a promise object whose fulfillment value is not matched by subPatt. For describing a top-level parameter, M.callWhen(..., M.await(p), ...) is preferred over M.call(..., M.eref(p), ...) because the former always checks against the sub-Pattern (awaiting fulfillment if necessary) while the latter bypasses such checks when the relevant argument is a promise.

Matches any error object. Error objects are Passable, but are neither Keys nor Patterns. They do not have a useful identity.

Matches any value that compareKeys reports as greater than rightOperand.

Matches any value that compareKeys reports as greater than or equal to rightOperand.

Matches any value that can be a key in a CopyMap or an element in a CopySet or CopyBag. All matched values are also valid Patterns that match only themselves.

When kind specifies a PassStyle other than "tagged", matches any value having that PassStyle. Otherwise, when kind specifies a known tagged record tag (such as 'copySet', 'copyBag', 'copyMap', or 'match:scalar'), matches any CopyTagged with that tag and a valid tag-specific payload. Otherwise, does not match any value. TODO: Reject attempts to create a kind matcher with unknown kind?

Matches any value that compareKeys reports as less than rightOperand.

Matches any value that compareKeys reports as less than or equal to rightOperand.

Matches any CopyMap, subject to limits.

Matches any CopyMap whose keys are all matched by keyPatt if defined and values are all matched by valuePatt if defined, subject to limits.

Matches any non-negative bigint, subject to limits.

Matches any value that is not equal to key.

Matches against the negation of the sub-Pattern.

Returns null, which matches only itself.

Matches any floating point number, including NaN and either signed Infinity.

Matches any Passable that is matched by subPatt or is the exact value undefined.

Matches against the union of all sub-Patterns (requiring a successful match against at least one).

Deprecated. Use M.splitArray or M.splitRecord instead. An array or record is split into the first part that is matched by basePatt, and the remainder, which is matched against rest if present. M.partial differs from M.split in the handling of data that is described in basePatt but absent in a provided specimen:

• For a CopyRecord, M.partial ignores properties of basePatt that are not present on the specimen.
• For a CopyArray, M.partial ignores elements of basePatt at indices beyond the maximum index of the specimen.

Matches any Pattern that can be used to characterize Passables. A Pattern cannot contain promises or errors, as these are not stable enough to usefully match.

Matches any promise object. Promises are Passable, but are neither Keys nor Patterns. They do not have a useful identity.

Matches any CopyRecord, subject to limits.

Matches any CopyRecord whose keys are all matched by keyPatt if defined and values are all matched by valuePatt if defined, subject to limits.

Matches a far object or its remote presence. The optional label is purely for diagnostic purposes and does not add any constraints.

Matches any Passable primitive value or Remotable. All matched values are Keys.

Matches any CopySet, subject to limits.

Matches any CopySet whose elements are all matched by keyPatt if defined, subject to limits.

Deprecated. Use M.splitArray or M.splitRecord instead. An array or record is split into the first part that is matched by basePatt, and the remainder, which is matched against rest if present.

Matches any array --- typically an arguments list --- consisting of

• an initial portion matched by required, and
• a middle portion of length up to the length of optional that is matched by the equal-length prefix of optional if optional is defined, and
• a remainder that is matched by rest if rest is defined. The array must be at least as long as required but its remainder can be arbitrarily short. Any array elements beyond the summed length of required and optional are collected and matched against rest.

Matches any CopyRecord that can be split into component CopyRecords as follows:

• all properties corresponding with a property of required
• all properties corresponding with a property of optional but not corresponding with a property of required
• all other properties where the first component is matched by required, the second component is matched by the subset of optional corresponding with its properties if optional is defined, and the third component is matched by rest if defined. The CopyRecord must have all properties that appear on required, but may omit properties that appear on optional.

Matches any string, subject to limits.

Matches any registered or well-known symbol, subject to limits.

For matching an arbitrary Passable Tagged object, whether it has a recognized kind or not. If tagPatt is omitted, it defaults to M.string(). If payloadPatt is omitted, it defaults to M.any().

Matches the exact value undefined. All keys including undefined are already valid Patterns and so can validly represent themselves. But optional Pattern arguments (patt = undefined) => ... treat explicit undefined as omission of the argument. Thus, when a passed Pattern does not also need to be a Key, we recommend passing M.undefined() rather than undefined.