Class: X12Decimal

String-backed decimal for X12 R-type elements. Immutable; arithmetic returns a new X12Decimal. Equality is mathematical ("0.00" equals "0"), not lexical - use toString() for byte-exact comparison.

Example

import { X12Decimal } from "@cosyte/x12";
const charge = X12Decimal.fromString("500.00");
const paid   = X12Decimal.fromString("450.00");
const due    = charge?.subtract(paid!);
due?.toString();  // "50.00"
due?.isZero();    // false

Properties

ZERO

readonly static ZERO: X12Decimal

Canonical zero with scale: 0 - "0". Used as the additive identity for balance reductions. Use X12Decimal.fromBigInt(0n, n) for a zero at a specific scale.

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.ZERO.toString();      // "0"
X12Decimal.ZERO.isZero();        // true

Methods

abs()

abs(): X12Decimal

Absolute value. Scale and lexical form may change (canonical rendering drops the leading -).

Returns

X12Decimal

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.fromString("-50.00")?.abs().toString();  // "50.00"

---

add()

add(other): X12Decimal

Add two X12Decimal values exactly. Result scale is max(this.scale, other.scale); result lexical form is canonical.

Parameters

other

X12Decimal

Returns

X12Decimal

Example

import { X12Decimal } from "@cosyte/x12";
const a = X12Decimal.fromString("0.1")!;
const b = X12Decimal.fromString("0.2")!;
a.add(b).toString();  // "0.3" - exact, never 0.30000000000000004

---

compareTo()

compareTo(other): -1 | 0 | 1

Three-way compare: -1 if this < other, 0 if equal, 1 if this > other. Mathematical compare across scales.

Parameters

other

X12Decimal

Returns

-1 | 0 | 1

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.fromString("10")!.compareTo(X12Decimal.fromString("9.99")!); // 1

---

equals()

equals(other): boolean

Mathematical equality across scales ("0.00" equals "0"). For byte-exact comparison use a.toString() === b.toString().

Parameters

other

X12Decimal

Returns

boolean

Example

import { X12Decimal } from "@cosyte/x12";
const a = X12Decimal.fromString("0.00")!;
const b = X12Decimal.fromString("0")!;
a.equals(b);                  // true
a.toString() === b.toString();// false ("0.00" vs "0")

---

isZero()

isZero(): boolean

True when this value is exactly zero (any scale).

Returns

boolean

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.fromString("0.00")?.isZero();  // true
X12Decimal.fromString("-50")?.isZero();   // false

---

negate()

negate(): X12Decimal

Arithmetic negation. abs() === negate() for negative values; for positive values flips sign; zero is its own negation.

Returns

X12Decimal

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.fromString("50.00")?.negate().toString();   // "-50.00"
X12Decimal.fromString("-50.00")?.negate().toString();  // "50.00"

---

signum()

signum(): -1 | 0 | 1

-1 / 0 / 1 indicating the sign of the value. Zero values (including "0.00" and "-0.00") always return 0.

Returns

-1 | 0 | 1

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.fromString("-50")?.signum();   // -1
X12Decimal.fromString("0.00")?.signum();  // 0
X12Decimal.fromString("0.01")?.signum();  // 1

---

subtract()

subtract(other): X12Decimal

Subtract other from this exactly. Result scale is max(this.scale, other.scale).

Parameters

other

X12Decimal

Returns

X12Decimal

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.fromString("500.00")!.subtract(X12Decimal.fromString("50")!).toString();
// "450.00"

---

toNumber()

toNumber(): number

Lossy conversion to JS number. JSDoc warns: number cannot represent every X12 monetary value exactly (0.1 + 0.2 !== 0.3). Helpers return X12Decimal, not number; use this only for display or when the loss is acceptable. Magnitudes large enough to lose precision (> Number.MAX_SAFE_INTEGER after scaling) still convert without throwing - silently lossy.

Returns

number

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.fromString("1234.56")?.toNumber(); // 1234.56 (typically exact)
X12Decimal.fromString("0.1")?.toNumber();     // 0.1 (lossy at higher precision)

---

toString()

toString(): string

Return the verbatim lexical form (for X12Decimal.fromString) or the canonical rendering (for arithmetic results / fromBigInt). Round-trip is byte-exact when the value was produced by fromString.

Returns

string

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.fromString("0050.00")?.toString();  // "0050.00" (verbatim)
X12Decimal.fromBigInt(5000n, 2).toString();    // "50.00" (canonical)

---

fromBigInt()

static fromBigInt(value, scale): X12Decimal

Construct an X12Decimal from a BigInt magnitude + scale (decimal places). Useful when arithmetic produces a result whose lexical form the caller wants to control. raw is rendered canonically (sign + integer + optional .fraction).

Parameters

value

bigint

scale

number

Returns

X12Decimal

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.fromBigInt(123456n, 2).toString();  // "1234.56"
X12Decimal.fromBigInt(-50n, 0).toString();     // "-50"
X12Decimal.fromBigInt(0n, 2).toString();       // "0.00"

---

fromString()

static fromString(raw): X12Decimal | undefined

Decode an X12 R-type decimal element into an X12Decimal, or undefined when the input is empty or does not match the shape [+-]?digits(.digits?)?. Empty string returns undefined, never zero - "not supplied" and "zero" are spec-distinct.

Parameters

raw

string

Returns

X12Decimal | undefined

Example

import { X12Decimal } from "@cosyte/x12";
X12Decimal.fromString("1234.56")?.toString(); // "1234.56"
X12Decimal.fromString("-50")?.signum();       // -1
X12Decimal.fromString("");                    // undefined
X12Decimal.fromString("1,234.56");            // undefined (X12 forbids thousands sep)