@tradik/xslt3 0.0.0-stage → 1.0.0

package/src/functions/format/formatNumber.js

@@ -0,0 +1,165 @@
+/**
+ * fn:format-number (F&O 3.1 section 4.7): the formatting phase of
+ * section 4.7.5 over the analysis of numberPicture.js, with decimal
+ * formats from decimalFormat.js. Numbers are formatted exactly: doubles
+ * and floats through the shortest decimal that reads back as them.
+ *
+ * @module @tradik/xslt3/functions/format/formatNumber
+ */
+
+import { Decimal } from "../../xdm/decimal.js";
+import { numberToDecimal } from "../../xdm/numeric.js";
+import { types } from "../../xdm/types.js";
+import { roundDecimal } from "../numeric.js";
+import { define, stringItem } from "../support.js";
+import { getDecimalFormat } from "./decimalFormat.js";
+import { analyzePicture } from "./numberPicture.js";
+
+/**
+ * Splits a decimal into mantissa and exponent with
+ * 10^(scaling-1) <= |mantissa| < 10^scaling.
+ * @param {Decimal} value - Non-negative
+ * @param {number} scaling
+ * @returns {{mantissa: Decimal, exponent: number}}
+ */
+function scale(value, scaling) {
+  if (value.sign() === 0) return { mantissa: value, exponent: 0 };
+  const length = value.unscaled.toString().length;
+  const exponent = length - value.scale - scaling;
+  return {
+    mantissa: Decimal.of(value.unscaled, value.scale + exponent),
+    exponent,
+  };
+}
+
+/**
+ * Inserts grouping separators into the digits of the integer part.
+ * @param {string} digits
+ * @param {import("./numberPicture.js").SubPicture} sub
+ * @param {string} separator
+ * @returns {string}
+ */
+function groupInteger(digits, sub, separator) {
+  let result = "";
+  for (let i = digits.length - 1, n = 0; i >= 0; i--, n++) {
+    const grouped = sub.grouping
+      ? n > 0 && n % sub.grouping === 0
+      : sub.integerGroups.includes(n) && n > 0;
+    result = digits[i] + (grouped ? separator : "") + result;
+  }
+  return result;
+}
+
+/**
+ * Formats the absolute value of a finite number with a sub-picture.
+ * @param {Decimal} value - Non-negative, already multiplied
+ * @param {import("./numberPicture.js").SubPicture} sub
+ * @param {import("./decimalFormat.js").DecimalFormat} format
+ * @returns {string}
+ */
+function formatAbsolute(value, sub, format) {
+  const { mantissa: unrounded, exponent } = sub.minExponent
+    ? scale(value, sub.scaling)
+    : { mantissa: value, exponent: 0 };
+  const mantissa = roundDecimal(unrounded, sub.maxFraction, true);
+  const [whole, fraction = ""] = mantissa.toString().split(".");
+  const integer = (whole === "0" ? "" : whole).padStart(sub.minInteger, "0");
+  let fractionDigits = fraction.padEnd(sub.minFraction, "0");
+  for (const position of [...sub.fractionGroups].reverse()) {
+    if (position < fractionDigits.length) {
+      fractionDigits =
+        fractionDigits.slice(0, position) +
+        format.groupingSeparator +
+        fractionDigits.slice(position);
+    }
+  }
+  let text = groupInteger(integer, sub, format.groupingSeparator);
+  // the separator also stays without one in the picture when the
+  // adjustments of 4.7.4 asked for fraction digits ("#e0" gives "0.2e0")
+  if (fractionDigits !== "") {
+    text += format.decimalSeparator + fractionDigits;
+  }
+  if (sub.minExponent) {
+    text +=
+      format.exponentSeparator +
+      (exponent < 0 ? format.minusSign : "") +
+      String(Math.abs(exponent)).padStart(sub.minExponent, "0");
+  }
+  const zero = format.zeroDigit.codePointAt(0);
+  return text.replace(/[0-9]/g, (d) => String.fromCodePoint(zero + Number(d)));
+}
+
+/**
+ * fn:format-number on an atomic numeric value.
+ * @param {import("../../xdm/atomic.js").AtomicValue|undefined} item -
+ *   Undefined for the empty sequence (formatted as NaN)
+ * @param {string} picture
+ * @param {import("./decimalFormat.js").DecimalFormat} format
+ * @returns {string}
+ */
+export function formatNumber(item, picture, format) {
+  const { positive, negative } = analyzePicture(picture, format);
+  const value = item?.value ?? NaN;
+  if (typeof value === "number" && Number.isNaN(value)) return format.nan;
+  const isNegative =
+    typeof value === "number"
+      ? value < 0 || Object.is(value, -0)
+      : typeof value === "bigint"
+        ? value < 0n
+        : value.sign() < 0;
+  const sub = isNegative ? negative : positive;
+  return sub.prefix + adjusted(item, sub, format) + sub.suffix;
+}
+
+/**
+ * The absolute value multiplied for percent or per-mille in the value's
+ * own type (doubles may overflow to infinity), formatted.
+ * @param {import("../../xdm/atomic.js").AtomicValue} item - Not NaN
+ * @param {import("./numberPicture.js").SubPicture} sub
+ * @param {import("./decimalFormat.js").DecimalFormat} format
+ * @returns {string}
+ */
+function adjusted(item, sub, format) {
+  const { value } = item;
+  let exact;
+  if (typeof value === "number") {
+    const isFloat = item.type.primitive === types.float;
+    const product = isFloat
+      ? Math.fround(value * sub.multiplier)
+      : value * sub.multiplier;
+    if (!Number.isFinite(product)) return format.infinity;
+    exact = numberToDecimal(Math.abs(product), isFloat);
+  } else {
+    exact = (value instanceof Decimal ? value : Decimal.of(value)).mul(
+      Decimal.of(BigInt(sub.multiplier)),
+    );
+    if (exact.sign() < 0) exact = exact.neg();
+  }
+  return formatAbsolute(exact, sub, format);
+}
+
+/**
+ * @param {Array<*>[]} args - [$value, $picture, $decimal-format-name?]
+ * @param {object} context
+ * @returns {Array<*>}
+ */
+const impl = ([value, [picture], name], context) => [
+  stringItem(
+    formatNumber(
+      value[0],
+      picture.value,
+      getDecimalFormat(name?.[0]?.value, context),
+    ),
+  ),
+];
+
+/** @type {import("../support.js").FunctionDefinition[]} */
+export const formatNumberFunctions = [
+  define("format-number", ["xs:numeric?", "xs:string"], "xs:string", impl),
+  define(
+    "format-number",
+    ["xs:numeric?", "xs:string", "xs:string?"],
+    "xs:string",
+    impl,
+  ),
+];

package/src/functions/format/fractionFormat.js

@@ -0,0 +1,80 @@
+/**
+ * The fractional seconds component [f] of the format-dateTime family
+ * (F&O 3.1 section 9.8.4.5): the digit pattern is applied to the reversed
+ * fraction digits, so grouping separators count from the decimal point,
+ * and excess digits are truncated, not rounded.
+ *
+ * @module @tradik/xslt3/functions/format/fractionFormat
+ */
+
+import { formatDigits, parseDigitPattern, zeroOf } from "./digitPattern.js";
+
+const isDigit = (c) => /^\p{Nd}$/u.test(c);
+const reverse = (s) => Array.from(s).reverse().join("");
+
+/**
+ * Applies the width modifier to a fractional seconds picture.
+ * @param {string[]} chars - Characters of the picture
+ * @param {number|null} minWidth
+ * @param {number|null} maxWidth
+ * @returns {string[]}
+ */
+function widen(chars, minWidth, maxWidth) {
+  const zero = String.fromCodePoint(zeroOf(chars.find(isDigit)));
+  const result = [...chars];
+  let mandatory = result.filter(isDigit).length;
+  for (let i = 0; i < result.length && mandatory < (minWidth ?? 0); i++) {
+    if (result[i] === "#") {
+      result[i] = zero;
+      mandatory++;
+    }
+  }
+  while (mandatory < (minWidth ?? 0)) {
+    result.push(zero);
+    mandatory++;
+  }
+  if (maxWidth !== null) {
+    let signs = result.filter((c) => c === "#" || isDigit(c)).length;
+    for (; signs < maxWidth; signs++) result.push("#");
+  }
+  return result;
+}
+
+/**
+ * Formats fractional seconds.
+ * @param {import("../../xdm/decimal.js").Decimal} second - Seconds value
+ * @param {import("./datePicture.js").Marker} marker - Component f
+ * @returns {string}
+ */
+export function formatFraction(second, marker) {
+  const { minWidth, maxWidth } = marker;
+  const token = Array.from(marker.first ?? "").some(isDigit)
+    ? marker.first
+    : "1";
+  const digits = (second.toString().split(".")[1] ?? "").replace(/0+$/, "");
+  const chars = Array.from(token);
+  if (maxWidth === null && chars.length === 1) {
+    // a single digit keeps all the digits of the value
+    const zero = zeroOf(token);
+    return (digits || "0")
+      .padEnd(minWidth ?? 1, "0")
+      .replace(/[0-9]/g, (d) => String.fromCodePoint(zero + Number(d)));
+  }
+  const pattern = parseDigitPattern(
+    reverse(widen(chars, minWidth, maxWidth).join("")),
+  );
+  const out = Array.from(
+    reverse(formatDigits(BigInt(reverse(digits) || "0"), pattern)),
+  );
+  const zero = String.fromCodePoint(pattern.zero);
+  let count = out.filter(isDigit).length;
+  while (
+    count > pattern.digits ||
+    (count > pattern.mandatory && out.at(-1) === zero)
+  ) {
+    out.pop();
+    count--;
+    while (!isDigit(out.at(-1))) out.pop();
+  }
+  return out.join("");
+}

package/src/functions/format/germanWords.js

@@ -0,0 +1,89 @@
+/**
+ * German numbers in words for format-integer and xsl:number with
+ * language "de" (F&O 3.1 section 4.6.1): cardinals ("einundzwanzig",
+ * "zweihunderteins", "eine Million") and ordinals with an ending
+ * ("dritte", "zehnter", "zwanzigsten"); digits take "." as ordinal mark.
+ *
+ * @module @tradik/xslt3/functions/format/germanWords
+ */
+
+const ONES = (
+  "null eins zwei drei vier fünf sechs sieben acht neun zehn elf zwölf " +
+  "dreizehn vierzehn fünfzehn sechzehn siebzehn achtzehn neunzehn"
+).split(" ");
+const TENS =
+  "  zwanzig dreißig vierzig fünfzig sechzig siebzig achtzig neunzig".split(
+    " ",
+  );
+const SCALES = [
+  [10n ** 18n, "Trillion", "Trillionen"],
+  [10n ** 15n, "Billiarde", "Billiarden"],
+  [10n ** 12n, "Billion", "Billionen"],
+  [10n ** 9n, "Milliarde", "Milliarden"],
+  [10n ** 6n, "Million", "Millionen"],
+];
+
+/**
+ * A number below one million as the first part of a compound: "ein"
+ * rather than "eins" at the end ("einundzwanzigtausend").
+ * @param {bigint} n - 1 to 999,999
+ * @returns {string}
+ */
+const prefixWords = (n) => cardinalBelowMillion(n).replace(/eins$/, "ein");
+
+/**
+ * German cardinal words below one million.
+ * @param {bigint} n - Non-negative
+ * @returns {string}
+ */
+function cardinalBelowMillion(n) {
+  if (n < 20n) return ONES[Number(n)];
+  if (n < 100n) {
+    const units = n % 10n;
+    const tens = TENS[Number(n / 10n)];
+    return units ? `${prefixWords(units)}und${tens}` : tens;
+  }
+  if (n < 1000n) {
+    const rest = n % 100n;
+    return `${prefixWords(n / 100n)}hundert${rest ? cardinalBelowMillion(rest) : ""}`;
+  }
+  const rest = n % 1000n;
+  return `${prefixWords(n / 1000n)}tausend${rest ? cardinalBelowMillion(rest) : ""}`;
+}
+
+/**
+ * German cardinal words, e.g. "einhundertvierunddreißig".
+ * @param {bigint} n - Non-negative
+ * @returns {string}
+ */
+export function germanCardinal(n) {
+  const scale = SCALES.find(([size]) => n >= size);
+  if (!scale) return cardinalBelowMillion(n);
+  const [size, one, many] = scale;
+  const count = n / size;
+  const rest = n % size;
+  const head =
+    count === 1n ? `eine ${one}` : `${germanCardinal(count)} ${many}`;
+  return rest ? `${head} ${germanCardinal(rest)}` : head;
+}
+
+/** Ordinal stems of the numbers whose ordinal is irregular. */
+const IRREGULAR = { 1: "erst", 3: "dritt", 7: "siebt", 8: "acht" };
+
+/**
+ * German ordinal words, e.g. "dritte", "zehnter", "zwanzigsten".
+ * @param {bigint} n - Non-negative
+ * @param {string} [form] - "-er", "-es"...: the ending (default "e");
+ *   other forms (such as "%spellout-ordinal") take the default
+ * @returns {string}
+ */
+export function germanOrdinal(n, form = "") {
+  const ending = form.startsWith("-") ? form.slice(1) : "e";
+  const last = n % 100n;
+  if (last === 0n || last >= 20n || n >= 10n ** 6n) {
+    return `${germanCardinal(n)}st${ending}`;
+  }
+  const head = n === last ? "" : germanCardinal(n - last);
+  const stem = IRREGULAR[Number(last)] ?? `${ONES[Number(last)]}t`;
+  return `${head}${stem}${ending}`;
+}

package/src/functions/format/numberLanguages.js

@@ -0,0 +1,41 @@
+/**
+ * The languages numbers are written in by format-integer, the format-date
+ * family and xsl:number: words (cardinal and ordinal) and the ordinal mark
+ * of digits. A language is chosen by the primary subtag of its tag
+ * ("de-AT" is "de"); others are English. Add a language by adding an
+ * entry to {@link NUMBER_LANGUAGES}.
+ *
+ * @module @tradik/xslt3/functions/format/numberLanguages
+ */
+
+import { germanCardinal, germanOrdinal } from "./germanWords.js";
+import { cardinalWords, ordinalSuffix, ordinalWords } from "./numberWords.js";
+
+/**
+ * How a language writes numbers.
+ * @typedef {object} NumberLanguage
+ * @property {(n: bigint) => string} cardinal - Lower-case words
+ * @property {(n: bigint, form: string) => string} ordinal - Lower-case
+ *   words; `form` is the text in parentheses of the "o" modifier, or the
+ *   ordinal attribute of xsl:number ("-er", "%spellout-ordinal"...)
+ * @property {(n: bigint) => string} suffix - Mark after ordinal digits
+ */
+
+/** @type {Readonly<Record<string, NumberLanguage>>} */
+export const NUMBER_LANGUAGES = Object.freeze({
+  en: { cardinal: cardinalWords, ordinal: ordinalWords, suffix: ordinalSuffix },
+  de: { cardinal: germanCardinal, ordinal: germanOrdinal, suffix: () => "." },
+});
+
+/**
+ * The number language of a language tag.
+ * @param {string|null} [tag] - e.g. "de", "en-GB"; English when absent
+ *   or not supported
+ * @returns {NumberLanguage}
+ */
+export function numberLanguage(tag) {
+  const primary = (tag ?? "").trim().toLowerCase().split("-")[0];
+  return Object.hasOwn(NUMBER_LANGUAGES, primary)
+    ? NUMBER_LANGUAGES[primary]
+    : NUMBER_LANGUAGES.en;
+}

package/src/functions/format/numberPicture.js

@@ -0,0 +1,202 @@
+/**
+ * Analysis of fn:format-number picture strings (F&O 3.1 sections 4.7.3
+ * and 4.7.4): syntax checks (FODF1310) and the variables of each
+ * sub-picture.
+ *
+ * @module @tradik/xslt3/functions/format/numberPicture
+ */
+
+import { pictureError, regularGrouping } from "./digitPattern.js";
+
+/**
+ * Variables of one sub-picture.
+ * @typedef {object} SubPicture
+ * @property {string} prefix
+ * @property {string} suffix
+ * @property {number[]} integerGroups - Grouping positions, from the
+ *   decimal separator leftwards
+ * @property {number} grouping - Regular grouping size, 0 when irregular
+ * @property {number[]} fractionGroups
+ * @property {number} minInteger
+ * @property {number} scaling
+ * @property {number} minFraction
+ * @property {number} maxFraction
+ * @property {number} minExponent - 0 without exponent
+ * @property {boolean} hasDecimal - Whether the decimal separator occurs
+ * @property {number} multiplier - 1, 100 (percent) or 1000 (per-mille)
+ */
+
+/**
+ * Classifies the characters of a sub-picture.
+ * @param {string[]} chars
+ * @param {import("./decimalFormat.js").DecimalFormat} format
+ * @returns {string[]} "digit", "optional", "decimal", "grouping",
+ *   "exponent" (candidate) or "passive" per character
+ */
+function classify(chars, format) {
+  const zero = format.zeroDigit.codePointAt(0);
+  return chars.map((c) => {
+    const cp = c.codePointAt(0);
+    if (cp >= zero && cp <= zero + 9) return "digit";
+    if (c === format.digit) return "optional";
+    if (c === format.decimalSeparator) return "decimal";
+    if (c === format.groupingSeparator) return "grouping";
+    if (c === format.exponentSeparator) return "exponent";
+    return "passive";
+  });
+}
+
+const count = (kinds, ...wanted) =>
+  kinds.filter((k) => wanted.includes(k)).length;
+
+/**
+ * Grouping positions of a part, counted from its decimal-separator side.
+ * @param {string[]} kinds - The part, ordered away from the separator
+ * @returns {number[]}
+ */
+function groupPositions(kinds) {
+  const positions = [];
+  let digits = 0;
+  for (const kind of kinds) {
+    if (kind === "grouping") positions.push(digits);
+    else digits++;
+  }
+  return positions;
+}
+
+/**
+ * Checks the syntax rules on the mantissa part.
+ * @param {string[]} integer - Kinds of the integer part
+ * @param {string[]} fraction - Kinds of the fractional part
+ * @param {boolean} hasDecimal
+ */
+function checkMantissa(integer, fraction, hasDecimal) {
+  const mantissa = [...integer, ...fraction];
+  if (count(mantissa, "digit", "optional") === 0) pictureError("no digit");
+  if (
+    integer.at(-1) === "grouping" ||
+    (hasDecimal && fraction[0] === "grouping") ||
+    mantissa.some((k, i) => k === "grouping" && mantissa[i + 1] === "grouping")
+  ) {
+    pictureError("misplaced grouping separator");
+  }
+  const firstDigit = integer.indexOf("digit");
+  if (firstDigit >= 0 && integer.indexOf("optional", firstDigit) >= 0) {
+    pictureError("optional digit after a mandatory digit");
+  }
+  const firstOptional = fraction.indexOf("optional");
+  if (firstOptional >= 0 && fraction.indexOf("digit", firstOptional) >= 0) {
+    pictureError("mandatory digit after an optional digit");
+  }
+}
+
+/**
+ * Analyzes one sub-picture.
+ * @param {string} picture
+ * @param {import("./decimalFormat.js").DecimalFormat} format
+ * @returns {SubPicture}
+ */
+export function analyzeSubPicture(picture, format) {
+  const chars = Array.from(picture);
+  const kinds = classify(chars, format);
+  const isActive = (k) => k !== "passive" && k !== "exponent";
+  const first = kinds.findIndex(isActive);
+  const last = kinds.findLastIndex(isActive);
+  const exponents = kinds
+    .map((k, i) => (k === "exponent" && i > first && i < last ? i : -1))
+    .filter((i) => i >= 0);
+  const marks = chars.filter(
+    (c) => c === format.percent || c === format.perMille,
+  );
+  if (first < 0) pictureError("no digit");
+  if (count(kinds, "decimal") > 1) pictureError("several decimal separators");
+  if (
+    marks.length > 1 ||
+    exponents.length > 1 ||
+    (marks.length && exponents.length)
+  ) {
+    pictureError("several percent, per-mille or exponent signs");
+  }
+  const exponent = exponents[0] ?? -1;
+  kinds.forEach((k, i) => {
+    if (!isActive(k) && i > first && i < last && i !== exponent) {
+      pictureError("passive character between active characters");
+    }
+  });
+  const mantissaEnd = exponent < 0 ? last + 1 : exponent;
+  const mantissa = kinds.slice(first, mantissaEnd);
+  const exponentPart = exponent < 0 ? [] : kinds.slice(exponent + 1, last + 1);
+  if (exponentPart.some((k) => k !== "digit")) {
+    pictureError("non-digit in the exponent");
+  }
+  const decimal = mantissa.indexOf("decimal");
+  const hasDecimal = decimal >= 0;
+  const integer = hasDecimal ? mantissa.slice(0, decimal) : mantissa;
+  const fraction = hasDecimal ? mantissa.slice(decimal + 1) : [];
+  checkMantissa(integer, fraction, hasDecimal);
+  return variables({
+    integer,
+    fraction,
+    hasDecimal,
+    minExponent: exponentPart.length,
+    prefix: chars.slice(0, first).join(""),
+    suffix: chars.slice(last + 1).join(""),
+    multiplier: marks[0] === format.percent ? 100 : marks.length ? 1000 : 1,
+  });
+}
+
+/**
+ * Computes the variables of section 4.7.4 from the parts.
+ * @param {object} parts
+ * @returns {SubPicture}
+ */
+function variables({ integer, fraction, hasDecimal, minExponent, ...rest }) {
+  const integerGroups = groupPositions([...integer].reverse());
+  const integerDigits = count(integer, "digit", "optional");
+  const separators = new Map(integerGroups.map((p) => [p, ","]));
+  let minInteger = count(integer, "digit");
+  let minFraction = count(fraction, "digit");
+  let maxFraction = count(fraction, "digit", "optional");
+  if (minInteger === 0 && maxFraction === 0) {
+    if (minExponent > 0) {
+      minFraction = 1;
+      maxFraction = 1;
+    } else {
+      minInteger = 1;
+    }
+  }
+  if (minExponent > 0 && minInteger === 0 && integer.includes("optional")) {
+    minInteger = 1;
+  }
+  if (minInteger === 0 && minFraction === 0) minFraction = 1;
+  return {
+    ...rest,
+    integerGroups,
+    grouping: regularGrouping(separators, integerDigits),
+    fractionGroups: groupPositions(fraction),
+    minInteger,
+    scaling: count(integer, "digit"),
+    minFraction,
+    maxFraction,
+    minExponent,
+    hasDecimal,
+  };
+}
+
+/**
+ * Analyzes a picture string into its positive and negative sub-pictures.
+ * @param {string} picture
+ * @param {import("./decimalFormat.js").DecimalFormat} format
+ * @returns {{positive: SubPicture, negative: SubPicture}}
+ * @throws {XPathError} FODF1310 for an invalid picture
+ */
+export function analyzePicture(picture, format) {
+  const parts = picture.split(format.patternSeparator);
+  if (parts.length > 2) pictureError("several pattern separators");
+  const positive = analyzeSubPicture(parts[0], format);
+  const negative =
+    parts.length === 2
+      ? analyzeSubPicture(parts[1], format)
+      : { ...positive, prefix: format.minusSign + positive.prefix };
+  return { positive, negative };
+}