@knowvah/dot-engine 0.1.0

package/src/util/printf-round.ts

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * C-printf-compatible decimal rounding.
+ *
+ * `Number.prototype.toFixed` and `Number.prototype.toPrecision` round exact
+ * binary-decimal ties (e.g. 1399.25 at 5 significant digits, 34.125 at 2
+ * fixed decimals — both exactly representable in float64) half-away-from-
+ * zero. C's snprintf ("%.Nf", "%.Ng") rounds exact ties half-to-even under
+ * the default FE_TONEAREST rounding mode, so a value that lands exactly on
+ * a tie diverges from native dot's DOT/xdot attribute output.
+ *
+ * Every finite float64 has an EXACT, finite decimal expansion (its
+ * denominator is a power of two, which always divides some power of ten).
+ * These functions decompose the IEEE-754 bit pattern into an exact integer
+ * mantissa and binary exponent, convert to an exact decimal digit string via
+ * BigInt scaling (multiply by 5^k to trade a factor of 2^k for 10^k), and
+ * round that EXACT digit string half-to-even at the target position. This
+ * never approximates with epsilon-based tie detection — the tie predicate
+ * (`remainder === half`) is computed on exact integers.
+ *
+ * @see lib/gvc/gvdevice.c:gvprintdouble (%.2f) · lib/common/output.c
+ *   (agxbprint "%.5g")
+ */
+
+/** Decompose a non-negative finite float64 into an exact integer mantissa
+ * and binary exponent such that `v === mantissa * 2**binExp`. */
+function decomposeFloat64(v: number): { mantissa: bigint; binExp: number } {
+  const buf = new DataView(new ArrayBuffer(8));
+  buf.setFloat64(0, v, false);
+  const hi = buf.getUint32(0, false);
+  const lo = buf.getUint32(4, false);
+  const expBits = (hi >>> 20) & 0x7ff;
+  const mantHi = BigInt(hi & 0xfffff);
+  const mantLo = BigInt(lo >>> 0);
+  let mantissa = (mantHi << 32n) | mantLo;
+  let binExp: number;
+  if (expBits === 0) {
+    // Subnormal: no implicit leading 1, exponent fixed at 2^-1074.
+    binExp = -1074;
+  } else {
+    mantissa |= 1n << 52n; // implicit leading 1
+    binExp = expBits - 1075; // bias 1023 + 52 mantissa bits
+  }
+  return { mantissa, binExp };
+}
+
+/**
+ * Exact canonical decimal digits of a non-negative finite float64: returns
+ * `digits` (a BigInt with no trailing zero digit, i.e. `digits % 10n !== 0n`
+ * unless `digits === 0n`) and `exponent10` such that
+ * `v === Number(digits) * 10**exponent10`.
+ */
+function exactDecimalDigits(v: number): { digits: bigint; exponent10: number } {
+  const { mantissa, binExp } = decomposeFloat64(v);
+  let digits: bigint;
+  let exponent10: number;
+  if (binExp >= 0) {
+    digits = mantissa << BigInt(binExp);
+    exponent10 = 0;
+  } else {
+    // mantissa * 2**binExp === mantissa * 5**(-binExp) * 10**binExp
+    digits = mantissa * 5n ** BigInt(-binExp);
+    exponent10 = binExp;
+  }
+  while (digits !== 0n && digits % 10n === 0n) {
+    digits /= 10n;
+    exponent10 += 1;
+  }
+  return { digits, exponent10 };
+}
+
+/** Round a non-negative BigInt to the nearest multiple of `10**dropCount`
+ * (dropCount >= 1), ties to even, returning the quotient. */
+function roundHalfEvenDrop(value: bigint, dropCount: number): bigint {
+  const divisor = 10n ** BigInt(dropCount);
+  const q = value / divisor;
+  const r = value % divisor;
+  const half = divisor / 2n; // exact: divisor is a power of ten >= 10, always even
+  if (r > half || (r === half && q % 2n === 1n)) return q + 1n;
+  return q;
+}
+
+/**
+ * Format `v` as C's `%.<decimals>f` would (fixed decimal places, rounded
+ * half-to-even on exact ties). Mirrors `Number.prototype.toFixed(decimals)`
+ * byte-for-byte on every non-tie input; only exact-tie inputs differ.
+ *
+ * @see lib/gvc/gvdevice.c:gvprintdouble
+ */
+export function printfFixed(v: number, decimals: number): string {
+  // Non-finite: the exact-decimal decomposition below reads the IEEE-754
+  // bit pattern as a finite mantissa, so Infinity/NaN would emit a spurious
+  // ~309-digit integer. Match the `toFixed` contract this helper replaces:
+  // it returns "Infinity"/"-Infinity"/"NaN" verbatim (canonicalized to the
+  // oracle's C printf "inf"/"nan" by the xdot comparator).
+  if (!Number.isFinite(v)) return v.toFixed(decimals);
+  if (v === 0) return decimals > 0 ? '0.' + '0'.repeat(decimals) : '0';
+  const sign = v < 0 ? '-' : '';
+  const { digits, exponent10 } = exactDecimalDigits(Math.abs(v));
+  // scaled = round(|v| * 10**decimals), computed exactly.
+  const shift = exponent10 + decimals;
+  const scaled = shift >= 0
+    ? digits * 10n ** BigInt(shift)
+    : roundHalfEvenDrop(digits, -shift);
+  if (decimals === 0) return sign + scaled.toString();
+  let s = scaled.toString();
+  if (s.length <= decimals) s = '0'.repeat(decimals - s.length + 1) + s;
+  const intPart = s.slice(0, s.length - decimals);
+  const fracPart = s.slice(s.length - decimals);
+  return sign + intPart + '.' + fracPart;
+}
+
+/**
+ * Format `v` with `sig` significant digits, using the same notational
+ * contract as `Number.prototype.toPrecision(sig)` — fixed form when the
+ * decimal exponent `e` (0-indexed power of ten of the leading digit)
+ * satisfies `-6 <= e < sig`, otherwise exponential form
+ * `d.ddd...e±N` (unpadded exponent, sign always present). Exact ties round
+ * half-to-even; every other input is byte-identical to `toPrecision(sig)`.
+ * Callers that need C's `%g` exponent threshold (`e < -4 || e >= precision`)
+ * or trailing-zero trimming apply that on top of this — unchanged from the
+ * pre-existing `toPrecision`-based behavior.
+ *
+ * @see lib/common/output.c:71 (agxbprint "%.5g")
+ */
+export function printfSig(v: number, sig: number): string {
+  // Non-finite: mirror the `toPrecision` contract this helper replaces
+  // ("Infinity"/"-Infinity"/"NaN"); the bit-decomposition below is only
+  // valid for finite magnitudes. (gfmt5 already short-circuits non-finite,
+  // but the contract must hold for every caller.)
+  if (!Number.isFinite(v)) return v.toPrecision(sig);
+  if (v === 0) return sig > 1 ? '0.' + '0'.repeat(sig - 1) : '0';
+  const sign = v < 0 ? '-' : '';
+  const { digits, exponent10 } = exactDecimalDigits(Math.abs(v));
+  const digitsStr0 = digits.toString();
+  const len = digitsStr0.length;
+  const decExp0 = len + exponent10; // value == 0.digitsStr0 * 10**decExp0
+  let digitsStr: string;
+  let decExp = decExp0;
+  if (len <= sig) {
+    digitsStr = digitsStr0 + '0'.repeat(sig - len);
+  } else {
+    const q = roundHalfEvenDrop(digits, len - sig);
+    let qStr = q.toString();
+    if (qStr.length > sig) {
+      // Carry overflow (e.g. 999 -> 1000): qStr is exactly "1" + sig zeros.
+      qStr = qStr.slice(0, sig);
+      decExp += 1;
+    }
+    digitsStr = qStr;
+  }
+  const e = decExp - 1;
+  if (e < -6 || e >= sig) {
+    const mantissa = sig > 1 ? digitsStr[0] + '.' + digitsStr.slice(1) : digitsStr[0];
+    return sign + mantissa + 'e' + (e >= 0 ? '+' : '-') + String(Math.abs(e));
+  }
+  if (e >= 0) {
+    const intPart = digitsStr.slice(0, e + 1);
+    const fracPart = digitsStr.slice(e + 1);
+    return sign + intPart + (fracPart.length > 0 ? '.' + fracPart : '');
+  }
+  return sign + '0.' + '0'.repeat(-(e + 1)) + digitsStr;
+}

package/src/util/xml.ts

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: EPL-2.0
+/**
+ * XML/SVG escaping.
+ *
+ * @see lib/util/xml.h
+ * @see lib/util/xml.c
+ */
+
+/** Options to tweak the behaviour of XML escaping. @see lib/util/xml.h:xml_flags_t */
+export interface XmlFlags {
+  /** Escape & unconditionally; also escape \n and \r. */
+  raw: boolean;
+  /** Escape '-' as -. */
+  dash: boolean;
+  /** Convert 2nd+ consecutive space to  . */
+  nbsp: boolean;
+  /** Encode non-ASCII as &#xNNNN;. */
+  utf8: boolean;
+}
+
+/**
+ * XML-escape a string.
+ *
+ * @see lib/util/xml.c:gv_xml_escape
+ */
+export function gvXmlEscape(s: string, flags: XmlFlags): string {
+  return XmlEscaper.escape(s, flags);
+}
+
+/**
+ * Internal helpers grouped into a class so each method is measured
+ * independently by complexity tooling. All methods are static.
+ */
+class XmlEscaper {
+  static escape(s: string, flags: XmlFlags): string {
+    let result = "";
+    let previous = "";
+    let pos = 0;
+    while (pos < s.length) {
+      const prev = s[pos];
+      const [fragment, consumed] = XmlEscaper.core(previous, s, pos, flags);
+      result += fragment;
+      previous = prev;
+      pos += consumed;
+    }
+    return result;
+  }
+
+  /**
+   * Escape one character/codepoint at s[pos].
+   * Returns [escaped_fragment, characters_consumed].
+   * Delegates to focused helpers to stay within CCN limit.
+   * @see lib/util/xml.c:xml_core
+   */
+  static core(
+    previous: string,
+    s: string,
+    pos: number,
+    flags: XmlFlags,
+  ): [string, number] {
+    const special = XmlEscaper.coreSpecial(previous, s, pos, flags);
+    if (special !== null) return special;
+    const code = s.charCodeAt(pos);
+    if (code > 0x7f && flags.utf8) return XmlEscaper.utf8Entity(s, pos);
+    return [s[pos], 1];
+  }
+
+  /**
+   * Handle all the fixed-escape cases (& < > - space " ' \n \r).
+   * Returns null when none of those cases applies.
+   * @see lib/util/xml.c:xml_core
+   */
+  static coreSpecial(
+    previous: string,
+    s: string,
+    pos: number,
+    flags: XmlFlags,
+  ): [string, number] | null {
+    const c = s[pos];
+    if (c === "&" && (flags.raw || !XmlEscaper.isEntity(s, pos))) {
+      return ["&amp;", 1];
+    }
+    if (c === "<") return ["&lt;", 1];
+    if (c === ">") return ["&gt;", 1];
+    if (c === '"') return ["&quot;", 1];
+    if (c === "'") return ["&#39;", 1];
+    if (c === "-" && flags.dash) return ["&#45;", 1];
+    if (c === " " && previous === " " && flags.nbsp) return ["&#160;", 1];
+    if (c === "\n" && flags.raw) return ["&#10;", 1];
+    if (c === "\r" && flags.raw) return ["&#13;", 1];
+    return null;
+  }
+
+  /**
+   * Return true if s[pos] (which is '&') starts a valid XML entity:
+   *   &[A-Za-z]+;      e.g. &Ccedil;
+   *   &#[0-9]*;        e.g. &#38;
+   *   &#x[0-9a-fA-F]*; e.g. &#x6C34;
+   * @see lib/util/xml.c:xml_isentity
+   */
+  static isEntity(s: string, pos: number): boolean {
+    let i = pos + 1; // skip the known '&'
+    if (i >= s.length || s[i] === ";") return false;
+    i = s[i] === "#" ? XmlEscaper.scanNumericRef(s, i) : XmlEscaper.scanNamedRef(s, i);
+    return i < s.length && s[i] === ";";
+  }
+
+  /** Scan a numeric entity body starting just after the '#'. */
+  static scanNumericRef(s: string, hashPos: number): number {
+    let i = hashPos + 1; // skip '#'
+    if (i < s.length && (s[i] === "x" || s[i] === "X")) {
+      i++;
+      while (i < s.length && XmlEscaper.isXDigit(s[i])) i++;
+    } else {
+      while (i < s.length && XmlEscaper.isDecDigit(s[i])) i++;
+    }
+    return i;
+  }
+
+  /** Scan a named entity body (alpha chars after the '&'). */
+  static scanNamedRef(s: string, start: number): number {
+    let i = start;
+    while (i < s.length && XmlEscaper.isAlpha(s[i])) i++;
+    return i;
+  }
+
+  /**
+   * Decode a multi-byte UTF-8 sequence at s[pos] and emit &#xNNNN;.
+   * @see lib/util/xml.c:xml_core (UTF-8 block)
+   */
+  static utf8Entity(s: string, pos: number): [string, number] {
+    const b0 = s.charCodeAt(pos) & 0xff;
+    const cp = XmlEscaper.decodeUtf8(s, pos, b0);
+    const consumed = XmlEscaper.utf8ByteLen(b0);
+    return [`&#x${cp.toString(16)};`, consumed];
+  }
+
+  /** Decode the codepoint value from a multi-byte UTF-8 sequence. */
+  static decodeUtf8(s: string, pos: number, b0: number): number {
+    if ((b0 >> 5) === 6) {
+      return ((b0 & 0x1f) << 6) | (s.charCodeAt(pos + 1) & 0x3f);
+    }
+    if ((b0 >> 4) === 14) {
+      return (
+        ((b0 & 0x0f) << 12) |
+        ((s.charCodeAt(pos + 1) & 0x3f) << 6) |
+        (s.charCodeAt(pos + 2) & 0x3f)
+      );
+    }
+    if ((b0 >> 3) === 30) {
+      return (
+        ((b0 & 0x07) << 18) |
+        ((s.charCodeAt(pos + 1) & 0x3f) << 12) |
+        ((s.charCodeAt(pos + 2) & 0x3f) << 6) |
+        (s.charCodeAt(pos + 3) & 0x3f)
+      );
+    }
+    throw new Error(`gvXmlEscape: malformed UTF-8 at position ${pos}`);
+  }
+
+  /** Return the byte-length of a UTF-8 sequence from its leading byte. */
+  static utf8ByteLen(b0: number): number {
+    if ((b0 >> 5) === 6) return 2;
+    if ((b0 >> 4) === 14) return 3;
+    if ((b0 >> 3) === 30) return 4;
+    throw new Error(`gvXmlEscape: invalid UTF-8 leading byte 0x${b0.toString(16)}`);
+  }
+
+  static isDecDigit(c: string): boolean {
+    return c >= "0" && c <= "9";
+  }
+
+  static isAlpha(c: string): boolean {
+    return (c >= "a" && c <= "z") || (c >= "A" && c <= "Z");
+  }
+
+  static isXDigit(c: string): boolean {
+    return (
+      XmlEscaper.isDecDigit(c) ||
+      (c >= "a" && c <= "f") ||
+      (c >= "A" && c <= "F")
+    );
+  }
+}