universal-physics-tensor 8.0.0 → 9.0.0

package/dist/dimensional/units.d.ts

@@ -1,58 +1,121 @@
 import type { Dimension } from './types.js';
+import { type ExactScale } from './exact-scale.js';
+/** An affine temperature scale: a lone `degC` or `degF`. @public */
+export type AffineTemperature = 'celsius' | 'fahrenheit';
 /** A unit, as a scale to SI base units and a dimension. @public */
 export interface ParsedUnit {
     readonly scale: number;
     readonly dim: Dimension;
     /** Set only for a lone affine temperature, which needs a reading. */
-    readonly affine?: 'celsius' | 'fahrenheit';
+    readonly affine?: AffineTemperature;
 }
 /** Thrown for any input that does not parse as a value with a known unit. @public */
 export declare class UnitError extends Error {
     constructor(message: string);
 }
+/** A symbol no table row and no prefix spells. @public */
+export declare class UnknownUnitError extends UnitError {
+    readonly symbol: string;
+    constructor(symbol: string);
+}
+/**
+ * A unit the reader recognizes and refuses: a logarithmic or ratio unit, an
+ * ambiguous name such as `ton`, or an affine temperature inside a compound.
+ * @public
+ */
+export declare class UnitRefusedError extends UnitError {
+    constructor(message: string);
+}
+/** A unit expression with more than one dimensionally distinct reading. @public */
+export declare class AmbiguousUnitError extends UnitError {
+    readonly text: string;
+    readonly readings: readonly string[];
+    constructor(text: string, readings: readonly string[]);
+}
 /**
- * Spellings that convert correctly and still mean something else to a reader.
- * `myr` is a milliyear, `Msun` is `M_SUN_SI`, bare `G` is the gauss, bare `T`
- * is the tesla, and bare `A` is the ampere rather than the angstrom.
+ * How a reading on an affine scale becomes kelvin, from the row's scale and
+ * ice point: `absolute: (degF − 32) × 5/9 + 273.15`, `a difference: × 5/9, no offset`.
+ * @internal
+ */
+export declare function affineReadingNote(affine: AffineTemperature, reading: TemperatureReading): string;
+/** One reading of a unit expression, with its exact scale. @internal */
+export interface UnitReading extends ParsedUnit {
+    readonly label: string;
+    readonly exact: ExactScale;
+    /** Net power of cycle-counting units (Hz, rpm): 1 for a lone `kHz`, 0 for `1/s`. */
+    readonly cycles: number;
+}
+/**
+ * Spellings that convert correctly and still mean something else to a reader:
+ * the `spellingNotes` of `data/units.json` for each symbol in `given`, in file
+ * order. `myr` is a milliyear, bare `G` is the gauss, bare `A` the ampere.
  * @internal
  */
 export declare function unitConventionNotes(given: string): string[];
+/** The one reading of a unit expression; more than one is refused. @internal */
+export declare function readUnit(text: string): UnitReading;
 /** Parse a unit expression; the empty string is dimensionless. @public */
 export declare function parseUnit(text: string): ParsedUnit;
 /** How a temperature value is read: as a point on the scale, or as a difference. @public */
 export type TemperatureReading = 'absolute' | 'difference';
-/** Kelvin added when this affine unit is an absolute point. @internal */
-export declare function affineAbsoluteOffsetK(id: 'celsius' | 'fahrenheit'): number;
+/** A number with a unit, read exactly and rounded once. @internal */
+export interface QuantityLiteral {
+    /** SI value; a bare number is unchanged. */
+    readonly value: number;
+    readonly dim: Dimension;
+    /** The unit text as given; `''` for a bare number. */
+    readonly unit: string;
+    readonly cycles: number;
+    readonly affine?: AffineTemperature;
+}
+/**
+ * Read `raw` as one number with an optional unit, in SI. Null when `raw` is
+ * not that form or names a unit no row spells, so the caller can read it as
+ * an expression. A refused unit and an ambiguous one throw. The value may be
+ * non-finite (`1e999`); the caller owns that refusal and its error class.
+ * @internal
+ */
+export declare function readQuantityLiteral(raw: string, temperature?: TemperatureReading): QuantityLiteral | null;
+/** A value converted into a declared unit. @public */
+export interface ConvertedValue {
+    readonly value: number;
+    /** The unit the user gave; `''` for a bare number. */
+    readonly given: string;
+    /** Net power of cycle-counting units in `given` (1 for `Hz` or `rpm`); absent when 0. */
+    readonly cycles?: number;
+    /** Set when `given` is a lone affine temperature. */
+    readonly affine?: AffineTemperature;
+}
 /**
  * Convert `raw` (`<number>[unit]`) into `target` (a unit expression). A bare
  * number is taken to be in `target` already. The dimensions must agree.
  *
+ * The magnitude, the unit scales and the target scale are multiplied as
+ * exact rationals and rounded once, so `1 g/cm^3` in `kg/m^3` is 1000.
+ *
  * @returns the value in `target`, and the unit the user gave (`''` for none).
  * @public
  */
-export declare function convertValue(raw: string, target: string, reading?: TemperatureReading): {
-    value: number;
-    given: string;
-};
+export declare function convertValue(raw: string, target: string, temperature?: TemperatureReading): ConvertedValue;
+/** The dimension of a declared unit expression. @internal */
+export declare function unitDimension(unit: string): Dimension;
+/** The symbols the unit table spells, with their exact scales, for the agreement test against MathTS. @internal */
+export declare function unitRows(): ReadonlyMap<string, {
+    readonly scale: ExactScale;
+    readonly dim: Dimension;
+    readonly prefixable: boolean;
+}>;
 /**
- * MathTS's SI value for `magnitude` of `unitText`, when that value and the
- * 7-base dimension agree with `local`. Affine °C stays on the local offset.
- * A symbol MathTS lacks, or a scale it disagrees with (`bit` is 1 there and
- * ln 2 here; a solar mass, a Julian year, and the gauss are absent), returns
- * undefined so the caller keeps the local table.
- *
+ * The tables conversion reads, for the CLI record's fingerprint (`src/cli/record-tables.ts`):
+ * each row's scale, dimension, prefixability and `cycles` flag (which multiplies an angular
+ * input by 2π), the prefixes, the Celsius offset, and the SHA-256 of `data/units.json`, so a
+ * refused spelling, a prefix letter, an affine row or a note that changes changes the fingerprint too.
  * @internal
  */
-export declare function mathTsAgreedQuantity(magnitude: number, unitText: string, local: ParsedUnit): {
-    value: number;
-    dim: Dimension;
-} | undefined;
-/** The dimension of a declared unit expression. @internal */
-export declare function unitDimension(unit: string): Dimension;
-/** The tables conversion reads, for the CLI record's fingerprint (`src/cli/record-tables.ts`). @internal */
 export declare function unitTables(): {
-    units: ReadonlyMap<string, readonly [number, Dimension, boolean]>;
+    units: ReadonlyMap<string, readonly [number, Dimension, boolean, boolean]>;
     prefixes: ReadonlyMap<string, number>;
     celsiusOffsetK: number;
+    sourceSha256: string;
 };
 //# sourceMappingURL=units.d.ts.map

package/dist/dimensional/units.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/dimensional/units.ts"],"names":[],"mappings":"AA2CA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAK5C,mEAAmE;AACnE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;CAC5C;AAED,qFAAqF;AACrF,qBAAa,SAAU,SAAQ,KAAK;IAClC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAmUD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAgB3D;AAED,0EAA0E;AAC1E,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAUlD;AAED,4FAA4F;AAC5F,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,YAAY,CAAC;AAE3D,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,SAAS,GAAG,YAAY,GAAG,MAAM,CAI1E;AASD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAA+B,GACvC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA0BlC;AA6CD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,GAChB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,CAU/C;AAOD,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAErD;AAED,4GAA4G;AAC5G,wBAAgB,UAAU,IAAI;IAC5B,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC;IAClE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,cAAc,EAAE,MAAM,CAAC;CACxB,CAEA"}
+{"version":3,"file":"units.d.ts","sourceRoot":"","sources":["../../src/dimensional/units.ts"],"names":[],"mappings":"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"}