@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/functions/registry.js

@@ -0,0 +1,140 @@
+/**
+ * The function library: definitions of built-in or extension functions,
+ * looked up by expanded name and arity.
+ *
+ * Function modules export arrays of definitions:
+ *
+ * ```js
+ * export const stringFunctions = [{
+ *   local: "upper-case",
+ *   params: ["xs:string?"],
+ *   returns: "xs:string",
+ *   impl: ([arg]) => [stringItem((arg[0]?.value ?? "").toUpperCase())],
+ * }];
+ * ```
+ *
+ * The evaluator applies the function conversion rules (atomization,
+ * xs:untypedAtomic casting, numeric promotion, cardinality checks) to the
+ * arguments before calling `impl`, so `impl` receives sequences of the
+ * declared types.
+ *
+ * @module @tradik/xslt3/functions/registry
+ */
+
+import { NS } from "./signatures.js";
+
+/**
+ * @typedef {object} FunctionDefinition
+ * @property {string} [namespace] - Default
+ *   "http://www.w3.org/2005/xpath-functions"; math:
+ *   ".../xpath-functions/math", map: ".../xpath-functions/map", array:
+ *   ".../xpath-functions/array"
+ * @property {string} local - Local name, e.g. "upper-case"
+ * @property {string[]} params - Parameter sequence types in XPath syntax,
+ *   e.g. ["xs:string?", "item()*"]; the arity is params.length
+ * @property {string} returns - Result sequence type
+ * @property {boolean} [variadic] - The last parameter repeats (fn:concat):
+ *   any arity from params.length up is accepted
+ * @property {boolean} [focus] - Needs the focus (context item, position,
+ *   size)
+ * @property {(args: Array<Array>, context: DynamicContext) => Array} impl
+ *   - Implementation: one sequence per argument, returns a sequence
+ */
+
+/**
+ * The context passed to implementations.
+ * @typedef {object} DynamicContext
+ * @property {number} implicitTimezone - Minutes
+ * @property {import("../xdm/datetime.js").DateTimeValue} currentDateTime
+ * @property {string} defaultCollation - Collation URI
+ * @property {string|undefined} staticBaseUri
+ * @property {string} defaultLanguage - "en"
+ * @property {*} contextItem - Focus (focus functions only), undefined when
+ *   absent
+ * @property {number} position
+ * @property {number} size
+ * @property {(uri: string) => Node} loadDocument - Loads a document
+ *   (FODC0002 when it cannot)
+ * @property {(href: string, encoding?: string) => string} loadText - Loads
+ *   and decodes a text resource, href resolved against the static base URI
+ *   (FOUT1170, FOUT1190, FOUT1200; see xpath/eval/resources.js)
+ * @property {(text: string, baseUri?: string) => Document} parseXml -
+ *   Parses an XML document (throws when it is not well-formed)
+ * @property {(href: string|null) => Array} collection - The items of a
+ *   collection, null for the default one (FODC0002 when unknown)
+ * @property {() => Document} createDocument - A new empty document, for
+ *   functions that build nodes
+ */
+
+/** A set of function definitions. */
+export class FunctionLibrary {
+  /**
+   * @param {FunctionDefinition[]} definitions - Later definitions replace
+   *   earlier ones of the same name and arity
+   */
+  constructor(definitions) {
+    /** @type {Map<string, {fixed: Map<number, FunctionDefinition>, variadic: FunctionDefinition[]}>} */
+    this.byName = new Map();
+    this.definitions = definitions;
+    for (const definition of definitions) {
+      const key = FunctionLibrary.key(
+        definition.namespace ?? NS.fn,
+        definition.local,
+      );
+      let entry = this.byName.get(key);
+      if (!entry) {
+        entry = { fixed: new Map(), variadic: [] };
+        this.byName.set(key, entry);
+      }
+      if (definition.variadic) entry.variadic.push(definition);
+      else entry.fixed.set(definition.params.length, definition);
+    }
+  }
+
+  /**
+   * @param {string} namespace
+   * @param {string} local
+   * @returns {string} lookup key (Clark notation)
+   */
+  static key(namespace, local) {
+    return `{${namespace}}${local}`;
+  }
+
+  /**
+   * @param {string} namespace - Namespace URI
+   * @param {string} local - Local name
+   * @param {number} arity - Number of arguments
+   * @returns {FunctionDefinition|null} the definition, null when unknown
+   */
+  lookup(namespace, local, arity) {
+    const entry = this.byName.get(FunctionLibrary.key(namespace, local));
+    if (!entry) return null;
+    const fixed = entry.fixed.get(arity);
+    if (fixed) return fixed;
+    for (let i = entry.variadic.length - 1; i >= 0; i--) {
+      if (arity >= entry.variadic[i].params.length) return entry.variadic[i];
+    }
+    return null;
+  }
+
+  /**
+   * @param {...FunctionDefinition[]} definitionArrays - More modules
+   * @returns {FunctionLibrary} a library with these definitions added
+   */
+  extend(...definitionArrays) {
+    return new FunctionLibrary([
+      ...this.definitions,
+      ...definitionArrays.flat(),
+    ]);
+  }
+}
+
+/**
+ * Creates a function library from modules.
+ * @param {...FunctionDefinition[]} definitionArrays - Arrays of definitions
+ * @returns {FunctionLibrary}
+ * @example createFunctionLibrary(coreFunctions, stringFunctions)
+ */
+export function createFunctionLibrary(...definitionArrays) {
+  return new FunctionLibrary(definitionArrays.flat());
+}

package/src/functions/sequences.js

@@ -0,0 +1,173 @@
+/**
+ * Functions on sequences (F&O 3.1 sections 14.1 to 14.2.6) that need no
+ * node access: head, tail, insert-before, remove, reverse, subsequence,
+ * unordered, index-of, distinct-values, the cardinality checks and
+ * deep-equal. fn:empty, fn:exists and fn:count belong to the core library.
+ *
+ * @module @tradik/xslt3/functions/sequences
+ */
+
+import { XPathError } from "../errors.js";
+import { compareAtomic, deepEqualAtomic } from "../xdm/compare.js";
+import { DateTimeValue } from "../xdm/datetime.js";
+import { timelineSeconds } from "../xdm/timeline.js";
+import { isNumericType } from "../xdm/types.js";
+import { collationArg } from "./collations.js";
+import { deepEqualSequences } from "./deepEqual.js";
+import { selectRange } from "./strings.js";
+import { booleanItem, define, integerItem } from "./support.js";
+
+/**
+ * Comparison options for a collation argument and the context.
+ * @param {Array<*>|undefined} collation
+ * @param {object} context
+ * @returns {{collation: Function, implicitTimezone: number, key: Function|null}}
+ */
+function compareOptions(collation, context) {
+  const resolved = collationArg(collation, context);
+  return {
+    collation: resolved.compare,
+    implicitTimezone: context.implicitTimezone ?? 0,
+    key: resolved.key,
+  };
+}
+
+/**
+ * Bucket key of an atomic value for distinct-values: values that may be
+ * equal share a key; equality is then checked with deepEqualAtomic.
+ * @param {import("../xdm/atomic.js").AtomicValue} item
+ * @param {object} options - From {@link compareOptions}
+ * @returns {string}
+ */
+function bucketKey(item, options) {
+  const { type, value } = item;
+  const primitive = type.primitive.localName;
+  // equal numbers of different types share the float nearest to them
+  if (isNumericType(type)) return `n${Math.fround(Number(value.toString()))}`;
+  if (["string", "anyURI", "untypedAtomic"].includes(primitive)) {
+    return options.key ? `s${options.key(value)}` : "s";
+  }
+  if (primitive === "duration") return `d${value.seconds}`;
+  if (value instanceof DateTimeValue) {
+    return `${primitive}${timelineSeconds(value, options.implicitTimezone)}`;
+  }
+  return primitive;
+}
+
+/**
+ * fn:distinct-values.
+ * @param {Array<*>[]} args - [$arg, $collation?]
+ * @param {object} context
+ * @returns {Array<*>}
+ */
+function distinctValues([items, collation], context) {
+  const options = compareOptions(collation, context);
+  const buckets = new Map();
+  const result = [];
+  for (const item of items) {
+    const key = bucketKey(item, options);
+    const bucket = buckets.get(key) ?? [];
+    if (!bucket.some((seen) => deepEqualAtomic(seen, item, options))) {
+      bucket.push(item);
+      buckets.set(key, bucket);
+      result.push(item);
+    }
+  }
+  return result;
+}
+
+/**
+ * fn:index-of: positions of the items `eq` to the search value
+ * (incomparable values and NaN are never equal).
+ * @param {Array<*>[]} args - [$seq, $search, $collation?]
+ * @param {object} context
+ * @returns {Array<*>}
+ */
+function indexOf([items, [search], collation], context) {
+  const options = compareOptions(collation, context);
+  const positions = [];
+  items.forEach((item, i) => {
+    try {
+      if (compareAtomic(item, search, options).order === 0) {
+        positions.push(integerItem(i + 1));
+      }
+    } catch (error) {
+      if (!(error instanceof XPathError)) throw error;
+    }
+  });
+  return positions;
+}
+
+/**
+ * Declares a cardinality check.
+ * @param {string} local
+ * @param {string} returns
+ * @param {(n: number) => boolean} accept
+ * @param {string} code - Error raised otherwise
+ * @returns {import("./support.js").FunctionDefinition}
+ */
+const cardinality = (local, returns, accept, code) =>
+  define(local, ["item()*"], returns, ([items]) => {
+    if (!accept(items.length)) {
+      throw new XPathError(code, `${local} called with ${items.length} items`);
+    }
+    return items;
+  });
+
+/** @param {Array<*>[]} args @returns {Array<*>} fn:subsequence */
+const subsequence = ([items, [start], length]) =>
+  items.slice(...selectRange(items.length, start.value, length?.[0].value));
+
+/**
+ * fn:deep-equal; nodes are compared by deepEqual.js, maps, arrays and
+ * function items by the `context.deepEqualItem` hook.
+ * @param {Array<*>[]} args - [$p1, $p2, $collation?]
+ * @param {object} context
+ * @returns {Array<*>}
+ */
+function deepEqual([a, b, collation], context) {
+  const options = compareOptions(collation, context);
+  options.deepEqualItem = context.deepEqualItem;
+  return [booleanItem(deepEqualSequences(a, b, options))];
+}
+
+const ITEMS = "item()*";
+const ATOMS = "xs:anyAtomicType*";
+
+/** @type {import("./support.js").FunctionDefinition[]} */
+export const sequenceFunctions = [
+  define("head", [ITEMS], "item()?", ([items]) => items.slice(0, 1)),
+  define("tail", [ITEMS], ITEMS, ([items]) => items.slice(1)),
+  define(
+    "insert-before",
+    [ITEMS, "xs:integer", ITEMS],
+    ITEMS,
+    ([target, [position], inserts]) => {
+      const p = position.value;
+      const at =
+        p < 1n ? 0 : p > BigInt(target.length) ? target.length : Number(p) - 1;
+      return [...target.slice(0, at), ...inserts, ...target.slice(at)];
+    },
+  ),
+  define("remove", [ITEMS, "xs:integer"], ITEMS, ([target, [position]]) =>
+    target.filter((_item, i) => BigInt(i + 1) !== position.value),
+  ),
+  define("reverse", [ITEMS], ITEMS, ([items]) => [...items].reverse()),
+  define("subsequence", [ITEMS, "xs:double"], ITEMS, subsequence),
+  define("subsequence", [ITEMS, "xs:double", "xs:double"], ITEMS, subsequence),
+  define("unordered", [ITEMS], ITEMS, ([items]) => items),
+  define("index-of", [ATOMS, "xs:anyAtomicType"], "xs:integer*", indexOf),
+  define(
+    "index-of",
+    [ATOMS, "xs:anyAtomicType", "xs:string"],
+    "xs:integer*",
+    indexOf,
+  ),
+  define("distinct-values", [ATOMS], ATOMS, distinctValues),
+  define("distinct-values", [ATOMS, "xs:string"], ATOMS, distinctValues),
+  cardinality("zero-or-one", "item()?", (n) => n <= 1, "FORG0003"),
+  cardinality("one-or-more", "item()+", (n) => n >= 1, "FORG0004"),
+  cardinality("exactly-one", "item()", (n) => n === 1, "FORG0005"),
+  define("deep-equal", [ITEMS, ITEMS], "xs:boolean", deepEqual),
+  define("deep-equal", [ITEMS, ITEMS, "xs:string"], "xs:boolean", deepEqual),
+];

package/src/functions/serializeFunction.js

@@ -0,0 +1,53 @@
+/**
+ * fn:serialize (F&O 3.1 section 14.6.3): the serialization of a sequence
+ * as a string, with parameters given as an output:serialization-parameters
+ * element or as a map. The defaults are those of the F&O table: the xml
+ * method, no indentation, and no XML declaration.
+ *
+ * @module @tradik/xslt3/functions/serializeFunction
+ */
+
+import { XPathError } from "../errors.js";
+import { serialize } from "../serialize/index.js";
+import { parametersFromElement } from "../serialize/params/fromElement.js";
+import { parametersFromMap } from "../serialize/params/fromMap.js";
+import { isMap, isNode } from "../xdm/index.js";
+import { define, stringItem } from "./support.js";
+
+/** Defaults of fn:serialize that differ from the serializer's. */
+const FN_DEFAULTS = Object.freeze({ "omit-xml-declaration": true });
+
+/**
+ * The parameters of the optional second argument.
+ * @param {*} [options] - Element, map or undefined
+ * @returns {Record<string, *>}
+ * @throws {XPathError} XPTY0004 for other items
+ */
+function parametersOf(options) {
+  if (options === undefined) return {};
+  if (isMap(options)) return parametersFromMap(options);
+  if (isNode(options)) return parametersFromElement(options);
+  throw new XPathError(
+    "XPTY0004",
+    "The parameters of fn:serialize must be an element or a map",
+  );
+}
+
+/**
+ * @param {Array} sequence
+ * @param {*} [options]
+ * @returns {Array} the serialization as an xs:string
+ */
+const serializeSequence = (sequence, options) => [
+  stringItem(serialize(sequence, { ...FN_DEFAULTS, ...parametersOf(options) })),
+];
+
+/** fn:serialize#1 and fn:serialize#2. */
+export const serializeFunctions = [
+  define("serialize", ["item()*"], "xs:string", ([arg]) =>
+    serializeSequence(arg),
+  ),
+  define("serialize", ["item()*", "item()?"], "xs:string", ([arg, options]) =>
+    serializeSequence(arg, options[0]),
+  ),
+];

package/src/functions/signatures.js

@@ -0,0 +1,105 @@
+/**
+ * Names and arities of the functions of XPath and XQuery Functions and
+ * Operators 3.1 (fn:, math:, map:, array:), used by static analysis to tell
+ * a known function from an unknown one (XPST0017) before every function
+ * has an implementation registered. A function listed here but missing from
+ * the function library compiles, and raises XPST0017 "not implemented" when
+ * it is called.
+ *
+ * @module @tradik/xslt3/functions/signatures
+ */
+
+/** Namespace URIs of the function libraries. */
+export const NS = Object.freeze({
+  fn: "http://www.w3.org/2005/xpath-functions",
+  math: "http://www.w3.org/2005/xpath-functions/math",
+  map: "http://www.w3.org/2005/xpath-functions/map",
+  array: "http://www.w3.org/2005/xpath-functions/array",
+});
+
+/**
+ * Per namespace: "name arities" entries; arities are "1", "0-2", "2,5" or
+ * "2+" (variadic).
+ */
+const CATALOG = {
+  fn: `abs 1|adjust-date-to-timezone 1-2|adjust-dateTime-to-timezone 1-2|
+adjust-time-to-timezone 1-2|analyze-string 2-3|apply 2|
+available-environment-variables 0|avg 1|base-uri 0-1|boolean 1|ceiling 1|
+codepoint-equal 2|codepoints-to-string 1|collation-key 1-2|collection 0-1|
+compare 2-3|concat 2+|contains 2-3|contains-token 2-3|count 1|current-date 0|
+current-dateTime 0|current-time 0|data 0-1|dateTime 2|day-from-date 1|
+day-from-dateTime 1|days-from-duration 1|deep-equal 2-3|default-collation 0|
+default-language 0|distinct-values 1-2|doc 1|doc-available 1|document-uri 0-1|
+element-with-id 1-2|empty 1|encode-for-uri 1|ends-with 2-3|
+environment-variable 1|error 0-3|escape-html-uri 1|exactly-one 1|exists 1|
+false 0|filter 2|floor 1|fold-left 3|fold-right 3|for-each 2|for-each-pair 3|
+format-date 2,5|format-dateTime 2,5|format-integer 2-3|format-number 2-3|
+format-time 2,5|function-arity 1|function-lookup 2|function-name 1|
+generate-id 0-1|has-children 0-1|head 1|hours-from-dateTime 1|
+hours-from-duration 1|hours-from-time 1|id 1-2|idref 1-2|implicit-timezone 0|
+in-scope-prefixes 1|index-of 2-3|innermost 1|insert-before 3|iri-to-uri 1|
+json-doc 1-2|json-to-xml 1-2|lang 1-2|last 0|load-xquery-module 1-2|
+local-name 0-1|local-name-from-QName 1|lower-case 1|matches 2-3|max 1-2|
+min 1-2|minutes-from-dateTime 1|minutes-from-duration 1|minutes-from-time 1|
+month-from-date 1|month-from-dateTime 1|months-from-duration 1|name 0-1|
+namespace-uri 0-1|namespace-uri-for-prefix 2|namespace-uri-from-QName 1|
+nilled 0-1|node-name 0-1|normalize-space 0-1|normalize-unicode 1-2|not 1|
+number 0-1|one-or-more 1|outermost 1|parse-ietf-date 1|parse-json 1-2|
+parse-xml 1|parse-xml-fragment 1|path 0-1|position 0|prefix-from-QName 1|
+QName 2|random-number-generator 0-1|remove 2|replace 3-4|resolve-QName 2|
+resolve-uri 1-2|reverse 1|root 0-1|round 1-2|round-half-to-even 1-2|
+seconds-from-dateTime 1|seconds-from-duration 1|seconds-from-time 1|
+serialize 1-2|sort 1-3|starts-with 2-3|static-base-uri 0|string 0-1|
+string-join 1-2|string-length 0-1|string-to-codepoints 1|subsequence 2-3|
+substring 2-3|substring-after 2-3|substring-before 2-3|sum 1-2|tail 1|
+timezone-from-date 1|timezone-from-dateTime 1|timezone-from-time 1|
+tokenize 1-3|trace 1-2|transform 1|translate 3|true 0|unordered 1|
+unparsed-text 1-2|unparsed-text-available 1-2|unparsed-text-lines 1-2|
+upper-case 1|uri-collection 0-1|xml-to-json 1-2|year-from-date 1|
+year-from-dateTime 1|years-from-duration 1|zero-or-one 1`,
+  math: `acos 1|asin 1|atan 1|atan2 2|cos 1|exp 1|exp10 1|log 1|log10 1|pi 0|
+pow 2|sin 1|sqrt 1|tan 1`,
+  map: `contains 2|entry 2|find 2|for-each 2|get 2|keys 1|merge 1-2|put 3|
+remove 2|size 1`,
+  array: `append 2|filter 2|flatten 1|fold-left 3|fold-right 3|for-each 2|
+for-each-pair 3|get 2|head 1|insert-before 3|join 1|put 3|remove 2|reverse 1|
+size 1|sort 1-3|subarray 2-3|tail 1`,
+};
+
+/**
+ * Parses an arity specification.
+ * @param {string} spec - "1", "0-2", "2,5" or "2+"
+ * @returns {(arity: number) => boolean} membership test
+ */
+function aritySet(spec) {
+  if (spec.endsWith("+")) {
+    const min = Number(spec.slice(0, -1));
+    return (arity) => arity >= min;
+  }
+  const allowed = new Set();
+  for (const part of spec.split(",")) {
+    const [low, high = low] = part.split("-").map(Number);
+    for (let n = low; n <= high; n++) allowed.add(n);
+  }
+  return (arity) => allowed.has(arity);
+}
+
+/** @type {Map<string, (arity: number) => boolean>} by Clark name */
+const known = new Map();
+for (const [prefix, text] of Object.entries(CATALOG)) {
+  for (const entry of text.replace(/\n/g, "").split("|")) {
+    const [name, spec] = entry.split(" ");
+    known.set(`{${NS[prefix]}}${name}`, aritySet(spec));
+  }
+}
+
+/**
+ * Whether F&O 3.1 defines a function with this name and arity.
+ * @param {string} namespace - Namespace URI
+ * @param {string} local - Local name
+ * @param {number} arity - Number of arguments
+ * @returns {boolean}
+ */
+export function isStandardFunction(namespace, local, arity) {
+  return known.get(`{${namespace}}${local}`)?.(arity) ?? false;
+}

package/src/functions/sort.js

@@ -0,0 +1,102 @@
+/**
+ * fn:sort (F&O 3.1 section 16.2.4): a stable sort on sort keys, which are
+ * compared item by item (NaN first, a prefix before a longer key).
+ *
+ * @module @tradik/xslt3/functions/sort
+ */
+
+import { XPathError } from "../errors.js";
+import { cast } from "../xdm/cast.js";
+import { compareAtomic } from "../xdm/compare.js";
+import { atomize } from "../xdm/nodes.js";
+import { types } from "../xdm/types.js";
+import { collationArg } from "./collations.js";
+
+/** @param {*} value @returns {boolean} whether an atomic value is NaN */
+const isNaNValue = (value) =>
+  typeof value.value === "number" && Number.isNaN(value.value);
+
+/**
+ * Compares two atomic values for sorting.
+ * @returns {number}
+ */
+function compareItems(a, b, options) {
+  if (isNaNValue(a) || isNaNValue(b)) {
+    return Number(isNaNValue(b)) - Number(isNaNValue(a));
+  }
+  const { order, ordered } = compareAtomic(a, b, options);
+  if (!ordered && order !== 0) {
+    throw new XPathError("XPTY0004", "Sort keys are not ordered");
+  }
+  return order;
+}
+
+/**
+ * Compares two sort keys (sequences of atomic values).
+ * @returns {number}
+ */
+export function compareKeys(a, b, options) {
+  const length = Math.min(a.length, b.length);
+  for (let i = 0; i < length; i++) {
+    const order = compareItems(a[i], b[i], options);
+    if (order !== 0) return order;
+  }
+  return a.length - b.length;
+}
+
+/**
+ * Sort key of an item: atomized, untyped values as strings.
+ * @param {Array} sequence
+ * @returns {Array}
+ */
+const sortKey = (sequence) =>
+  atomize(sequence).map((v) =>
+    v.type === types.untypedAtomic ? cast(v, types.string) : v,
+  );
+
+/**
+ * Sorts values by their sort keys (stable).
+ * @param {Array} values - Items (fn:sort) or members (array:sort)
+ * @param {Array|undefined} collation - Collation argument
+ * @param {*} f - Key function item, undefined for the values themselves
+ * @param {object} context
+ * @param {(value: *) => Array} asArgument - The argument of the key
+ *   function for a value
+ * @returns {Array} the values in order
+ */
+export function sortByKeys(values, collation, f, context, asArgument) {
+  const options = {
+    ...context.compareOptions,
+    collation: collationArg(collation, context).compare,
+  };
+  const keyed = values.map((value) => ({
+    value,
+    key: sortKey(f ? f.invoke([asArgument(value)]) : asArgument(value)),
+  }));
+  keyed.sort((x, y) => compareKeys(x.key, y.key, options));
+  return keyed.map(({ value }) => value);
+}
+
+/**
+ * fn:sort.
+ * @returns {Array}
+ */
+const sort = ([input, collation, key], context) =>
+  sortByKeys(input, collation, key?.[0], context, (item) => [item]);
+
+/** Function definitions. */
+export const sortFunctions = [
+  { local: "sort", params: ["item()*"], returns: "item()*", impl: sort },
+  {
+    local: "sort",
+    params: ["item()*", "xs:string?"],
+    returns: "item()*",
+    impl: sort,
+  },
+  {
+    local: "sort",
+    params: ["item()*", "xs:string?", "function(item()) as xs:anyAtomicType*"],
+    returns: "item()*",
+    impl: sort,
+  },
+];

package/src/functions/stringMatch.js

@@ -0,0 +1,45 @@
+/**
+ * Substring matching under a collation (F&O 3.1 section 5.5): contains,
+ * starts-with, ends-with, substring-before and substring-after, each with
+ * an optional collation argument.
+ *
+ * @module @tradik/xslt3/functions/stringMatch
+ */
+
+import { collationArg, findSubstring } from "./collations.js";
+import { booleanItem, define, stringArg, stringItem } from "./support.js";
+
+/**
+ * Declares a function of the family in both arities.
+ * @param {string} local
+ * @param {string} returns
+ * @param {(text: string, search: string, collation: object) => *} match
+ * @returns {import("./support.js").FunctionDefinition[]}
+ */
+function family(local, returns, match) {
+  const impl = ([arg1, arg2, collation], context) => [
+    match(stringArg(arg1), stringArg(arg2), collationArg(collation, context)),
+  ];
+  return [
+    define(local, ["xs:string?", "xs:string?"], returns, impl),
+    define(local, ["xs:string?", "xs:string?", "xs:string"], returns, impl),
+  ];
+}
+
+const found = (anchor) => (text, search, collation) =>
+  booleanItem(findSubstring(collation, text, search, anchor) !== null);
+
+/** @type {import("./support.js").FunctionDefinition[]} */
+export const stringMatchFunctions = [
+  ...family("contains", "xs:boolean", found(null)),
+  ...family("starts-with", "xs:boolean", found("start")),
+  ...family("ends-with", "xs:boolean", found("end")),
+  ...family("substring-before", "xs:string", (text, search, collation) => {
+    const match = findSubstring(collation, text, search);
+    return stringItem(match ? text.slice(0, match[0]) : "");
+  }),
+  ...family("substring-after", "xs:string", (text, search, collation) => {
+    const match = findSubstring(collation, text, search);
+    return stringItem(match ? text.slice(match[1]) : "");
+  }),
+];