# gizdb:decimal

Exact decimals, as PostgreSQL's NUMERIC: a value is C × 10^-s with a scale s of 0..16383 and at most 131072 digits before the point. A coefficient that fits an i64 (most values) is the `narrow` case: `c` and `s`, so columns and SIMD kernels work on `c` alone and a Dec stays 24 bytes (a wider Value made the decimal and integer sums 10-14% slower). A wider coefficient is the `wide` case: m[0] = s << 1 | sign, then |C| in base-10^9 limbs with the least significant first and no zero limb on top. Read a Dec through decScale, decCoef, decNegative and the limb helpers here. A value has one form at a scale, so `===` compares values of one scale. Every operation is exact, or rounds half away from zero at a scale it names, or reports overflow (none): nothing goes through binary floating point. ln, log, exp and power are correctly rounded at the scales PostgreSQL picks. Oracle's NUMBER keeps 40 digits by its own rule (`numberArith`, `decNumber`).

```gizlang
import * as Decimal from "gizdb:decimal";
```

## Types

### `Dec`

```gizlang
type Dec = | { kind: "narrow"; c: i64; s: i32; } | { kind: "wide"; m: Vec<u64>; }
```

An exact decimal: a 64-bit coefficient with its scale, or a wide sign-magnitude form for larger values.

- `narrow`
- `wide`

### `DecRead`

```gizlang
type DecRead = | { kind: "ok"; value: Dec; } | { kind: "invalid"; } | { kind: "overflow"; }
```

What a text spells as a decimal: a value, not a number, or a number past the limits.

- `ok`
- `invalid`
- `overflow`

### `Parts`

```gizlang
type Parts = { wh: i64; wl: u64; f1: u64; f2: u64; sticky: bool; more: Vec<u64>; }
```

A finite number split as floor(v), 128-bit two's complement (`wh` its high word, `wl` its low bits), and its
fraction in 10^-38 units (`f1` the first 19 digits, `f2` the next 19), with `sticky` when digits remain below
those: what orders and compares integers, floats and decimals exactly together. A decimal's digits past those
are `more`, 19 a word with no zero word last (a float's are not kept: it orders before a decimal of the same first
38 fraction digits). A floor from 2^127 on passes every float the parts compare with: it saturates.

- `wh`: `i64`
- `wl`: `u64`
- `f1`: `u64`
- `f2`: `u64`
- `sticky`: `bool`
- `more`: `Vec<u64>`

## Functions

### `pow10`

```gizlang
function pow10(n: i64): i64
```

10^n for 0 <= n <= 18.

Effects: fail.

### `decOf`

```gizlang
function decOf(c: i64, s: i64): Dec
```

A coefficient that fits an i64 at scale `s`.

### `decOfInt`

```gizlang
function decOfInt(x: i64): Dec
```

The decimal of the integer X.

### `narrow`

```gizlang
function narrow(d: Dec): bool
```

Whether the coefficient is `c` alone.

### `decNegative`

```gizlang
function decNegative(d: Dec): bool
```

Whether D is below zero.

Effects: fail.

### `decZero`

```gizlang
function decZero(d: Dec): bool
```

Whether D is zero.

### `decScale`

```gizlang
function decScale(d: Dec): i64
```

The scale.

Effects: fail.

### `decCoef`

```gizlang
function decCoef(d: Dec): i64
```

The coefficient of a narrow value; the sign (1 or -1) of a wide one.

Effects: fail.

### `decShift`

```gizlang
function decShift(d: Dec, s: i64): Dec
```

The same coefficient at scale `s`: d × 10^(scale - s).

Effects: fail.

### `decWithin`

```gizlang
function decWithin(d: Dec): bool
```

Whether a value is within NUMERIC's limits: scale 16383 and 131072 digits before the point.

Effects: fail.

### `precisionOf`

```gizlang
function precisionOf(d: Dec): i64
```

Significant digits of the coefficient: what DECIMAL(p, s) checks against p.

Effects: fail.

### `decWords`

```gizlang
function decWords(d: Dec): Vec<i64>
```

The coefficient as 64-bit two's complement words, the least significant first: one word when it fits an i64.

Effects: fail.

### `decOfWords`

```gizlang
function decOfWords(w: Vec<i64>, s: i64): Dec
```

The value of two's complement words (decWords) at scale `s`.

Effects: fail.

### `readDecimal`

```gizlang
function readDecimal(text: string): DecRead
```

The decimal a text spells, as PostgreSQL's numeric_in: [+-]digits[.digits][e[+-]digits], surrounding spaces
allowed. Every digit stays; the scale is the digits after the point less the exponent, at least 0.

Effects: fail.

### `parseDecimal`

```gizlang
function parseDecimal(text: string): Option<Dec>
```

readDecimal's value, or none for a text that is not a number or a number past the limits.

Effects: fail.

### `decOfFloat`

```gizlang
function decOfFloat(f: f64, scale: i64): Option<Dec>
```

The decimal of a float at its shortest exact digits, then rounded to `scale` (-1: as many as those digits have);
none for NaN, infinities and what does not fit.

Effects: fail.

### `decText`

```gizlang
function decText(d: Dec): string
```

The decimal as text at its scale: -12.340, 0.05, 7.

Effects: fail.

### `trimmed`

```gizlang
function trimmed(d: Dec): Dec
```

The same value without trailing fractional zeros (2.50 → 2.5, 3.00 → 3).

Effects: fail.

### `decFloat`

```gizlang
function decFloat(d: Dec): f64
```

The nearest f64 (correctly rounded, through the digits); ±infinity past the f64 range.

Effects: fail.

### `rescale`

```gizlang
function rescale(d: Dec, s: i64): Option<Dec>
```

The value at scale `s` (0..16383): more digits are exact, fewer round half away from zero; none on overflow.

Effects: fail.

### `cut`

```gizlang
function cut(d: Dec, s: i64, mode: string): Dec
```

Toward zero at scale `s` (s <= decScale(d)), or toward -∞ (`floor`) or +∞ (`ceil`).

Effects: fail.

### `decRound`

```gizlang
function decRound(d: Dec, scale: i64): Option<Dec>
```

PostgreSQL's round(d, scale): half away from zero at `scale`; a negative scale rounds to a multiple of 10^-scale
at scale 0. None on overflow.

Effects: fail.

### `decTrunc`

```gizlang
function decTrunc(d: Dec, scale: i64): Option<Dec>
```

PostgreSQL's trunc(d, scale): toward zero at `scale`; a negative scale truncates to a multiple of 10^-scale at
scale 0.

Effects: fail.

### `fitsPrecision`

```gizlang
function fitsPrecision(d: Dec, p: i64): bool
```

Whether the value is in DECIMAL(p, s) once at scale s: at most p - s integer digits.

Effects: fail.

### `decSum`

```gizlang
function decSum(x: Dec, y: Dec): Dec
```

The exact sum past the limits too: a running total that PostgreSQL checks only at its end (decWithin).

Effects: fail.

### `decDifference`

```gizlang
function decDifference(x: Dec, y: Dec): Dec
```

x - y, exact past the limits too (decSum).

Effects: fail.

### `decAdd`

```gizlang
function decAdd(x: Dec, y: Dec): Option<Dec>
```

The exact sum; none past the limits.

Effects: fail.

### `decNeg`

```gizlang
function decNeg(x: Dec): Option<Dec>
```

-X, or none when it does not fit.

Effects: fail.

### `decSub`

```gizlang
function decSub(x: Dec, y: Dec): Option<Dec>
```

X - Y, or none when it does not fit.

Effects: fail.

### `decMul`

```gizlang
function decMul(x: Dec, y: Dec): Option<Dec>
```

The exact product at scale decScale(x) + decScale(y), rounded half away at scale 16383 past it (as PostgreSQL's numeric_mul);
none past the limits.

Effects: fail.

### `decProduct`

```gizlang
function decProduct(x: Dec, y: Dec): Dec
```

The exact product at scale decScale(x) + decScale(y), past the limits too: a square inside variance, which
PostgreSQL keeps whole (decSum).

Effects: fail.

### `decDiv`

```gizlang
function decDiv(x: Dec, y: Dec): Option<Dec>
```

x / y as PostgreSQL's numeric division: at its select_div_scale, rounded half away. None for a zero divisor (the
caller reports it) and on overflow.

Effects: fail.

### `decDivTrunc`

```gizlang
function decDivTrunc(x: Dec, y: Dec): Option<Dec>
```

trunc(x / y) exactly, at scale 0 (PostgreSQL's div). None for a zero divisor and on overflow.

Effects: fail.

### `decMod`

```gizlang
function decMod(x: Dec, y: Dec): Option<Dec>
```

x - y × trunc(x / y): the sign of x, as SQL's % and MOD, at the larger scale. None for a zero divisor.

Effects: fail.

### `numberArith`

```gizlang
function numberArith(op: string, x: Dec, y: Dec): Option<Dec>
```

x op y (+ - * / %) as Oracle's NUMBER computes it: the exact result, or a quotient of 41 significant digits (one
past what NUMBER keeps, so its rounding is the exact quotient's), then numberFit. None for a zero divisor and on
overflow.

Effects: fail.

### `decCompareSum`

```gizlang
function decCompareSum(x: Dec, base: Dec, offset: Dec): i64
```

Compare x with base + offset without rounding the boundary.

Effects: fail.

### `decCompare`

```gizlang
function decCompare(x: Dec, y: Dec): i64
```

-1, 0 or 1, exactly.

Effects: fail.

### `decParts`

```gizlang
function decParts(d: Dec): Parts
```

D as a 128-bit whole part and two 19-digit fraction words, for a fast comparison (compareParts).

Effects: fail.

### `floatParts`

```gizlang
function floatParts(f: f64): Parts
```

The parts of a float with |f| < 2^127, exactly (from its bits, not its arithmetic).

Effects: fail.

### `compareParts`

```gizlang
function compareParts(a: Parts, b: Parts): i64
```

-1, 0 or 1 as A is less than, equal to or greater than B.

Effects: fail.

### `decCompareFloat`

```gizlang
function decCompareFloat(d: Dec, y: f64): i64
```

A decimal against a finite float, exactly.

Effects: fail.

### `intOf`

```gizlang
function intOf(d: Dec): Option<i64>
```

The value as an i64 when it is whole and fits one.

Effects: fail.

### `truncInt`

```gizlang
function truncInt(d: Dec): i64
```

Toward zero as an i64, saturating (SQLite's CAST of a huge number).

Effects: fail.

### `unitOf`

```gizlang
function unitOf(s: i64): f64
```

10^s as a float: what a coefficient at scale s is divided by.

### `sqrtScale`

```gizlang
function sqrtScale(x: Dec): i64
```

PostgreSQL's sqrt scale for x: 16 significant digits from its base-10000 weight, at least its scale, at most
1000.

Effects: fail.

### `decSqrt`

```gizlang
function decSqrt(x: Dec, scale: i64): Option<Dec>
```

The square root of x rounded half away at `scale`, as PostgreSQL's sqrt_var. None for a negative x.

Effects: fail.

### `decLn`

```gizlang
function decLn(x: Dec): Option<Dec>
```

ln(x) for x > 0 at PostgreSQL's scale.

Effects: fail.

### `decLog`

```gizlang
function decLog(b: Dec, x: Dec): Option<Dec>
```

The logarithm of x to base b, both > 0 and b not 1, at PostgreSQL's scale.

Effects: fail.

### `decExp`

```gizlang
function decExp(x: Dec): Option<Dec>
```

e^x at PostgreSQL's scale; none when it overflows.

Effects: fail.

### `decPow`

```gizlang
function decPow(x: Dec, y: Dec): Option<Dec>
```

x^y for finite x and y, where x is not negative or y is whole, and a zero x has y >= 0 (the caller reports the
other cases), at PostgreSQL's scale (power_var); none when it overflows.

Effects: fail.

## Constants

### `DEC_MAX_SCALE`

```gizlang
const DEC_MAX_SCALE = 16383
```

The largest scale (PostgreSQL's NUMERIC_DSCALE_MAX).

### `DEC_MAX_WHOLE`

```gizlang
const DEC_MAX_WHOLE = 131072
```

The most digits before the point: (NUMERIC_WEIGHT_MAX + 1) base-10000 digits.