# gizmodel/sql/types/types

SQL values: how a declared type is stored, what text a value reads as, casts, comparison, arithmetic, dates and intervals, and printing, for each dialect. Binary columns hold raw bytes distinct from text and NULL; DECIMAL/NUMERIC/NUMBER are exact decimals (decimal.giz) with exact arithmetic. The logical types SQL adds are read from the column's declared type: dates and timestamps are ISO-8601 text ('2024-05-01', '2024-05-01 13:45:00.25'), which sorts in time order and is what SQLite stores; BLOB/BYTEA render as hex only at text boundaries. JSON is text. Intervals exist only inside expressions, as text tagged with a leading \u0003 (`interval`).

```gizlang
import * as Types from "gizmodel/sql/types/types";
```

## Types

### `Assignment`

```gizlang
type Assignment = { kind: string; limit: i64; precision: i64; scale: i64; whole: i64; what: string; special: bool; width: i64; real: bool; }
```

whole: the most digits of an integer in Oracle's NUMBER(p) (p, else 0). width: intWidth. real: a float column keeps a
float4 (REAL, FLOAT4, Oracle's BINARY_FLOAT): each float value read its declared type in upper case (a sixth of an
INSERT ... SELECT of 4M rows with five float columns).

- `kind`: `string`
- `limit`: `i64`
- `precision`: `i64`
- `scale`: `i64`
- `whole`: `i64`
- `what`: `string`
- `special`: `bool`
- `width`: `i64`
- `real`: `bool`

### `TimeZone`

```gizlang
type TimeZone = { east: i64; zone: Option<Zone>; abbrev: bool; }
```

A time zone as AT TIME ZONE, make_timestamptz and date_trunc read it: `east` seconds east of UTC, or a tz
database zone whose offset changes with the instant. `abbrev`: the zone came from an abbreviation whose offset
changed over time (MSK); a local time takes the offset in effect at the instant the zone's rules give it, as
PostgreSQL's DetermineTimeZoneAbbrevOffset does.

- `east`: `i64`
- `zone`: `_gizlang_sdk_core.Option<gizlang_time.Zone>`
- `abbrev`: `bool`

## Functions

### `enumText`

```gizlang
function enumText(labels: Vec<string>): string
```

Enum catalog labels retain their declaration order. JSON preserves every label byte.

Effects: fail, alloc.

### `enumLabels`

```gizlang
function enumLabels(text: string): Vec<string> throws DbError
```

The labels of an enum type from their stored TEXT.

Effects: fail, alloc.

### `byteaValue`

```gizlang
function byteaValue(text: string): Value throws DbError
```

PostgreSQL bytea text input. Hex and legacy octal forms decode to the same native bytes.

Effects: fail, alloc.

### `logical`

```gizlang
function logical(declared: string, dialect: Dialect): string
```

The logical kind of a declared type: int, float, numeric, text, boolean, vector, date,
timestamp, time, json, blob.

Effects: fail, alloc.

### `plainFloat`

```gizlang
function plainFloat(x: string): Option<f64>
```

The double text X spells for a column that keeps doubles (keeps 2), when assign stores it as it is: finite and not zero,
which floatRange checks for out of range. COPY reads a float field here (copy.giz rawField), not through assign.

Effects: fail, alloc.

### `numberOf`

```gizlang
function numberOf(text: string): Option<Value>
```

The number a whole text spells (surrounding spaces allowed), as an int when it is one.

Effects: fail, alloc.

### `numeric`

```gizlang
function numeric(v: Value): Option<Value>
```

A value as a number for arithmetic: text by its numeric prefix (SQLite), booleans as 0/1;
none for NULL and vectors.

Effects: fail, alloc.

### `windowSumNumber`

```gizlang
function windowSumNumber(v: Value): Value
```

SQLite aggregate affinity keeps numeric text integral; junk prefixes contribute REAL.

Effects: fail, alloc.

### `asFloat`

```gizlang
function asFloat(v: Value): f64
```

V as a float: text by its numeric prefix, null and other kinds as 0.

Effects: fail, alloc.

### `asInt`

```gizlang
function asInt(v: Value): i64
```

V as an integer: text by its numeric prefix, null and other kinds as 0.

Effects: fail, alloc.

### `floatToInt`

```gizlang
function floatToInt(x: f64): i64
```

Truncation toward zero, saturating (SQLite's CAST of a huge REAL).

Effects: fail.

### `asText`

```gizlang
function asText(v: Value): string
```

V as text.

Effects: fail, alloc.

### `truth`

```gizlang
function truth(v: Value): i64
```

SQL truth: 1 true, 0 false, -1 unknown (NULL). Text reads as a boolean word (true, false,
t, f, yes, no, on, off) or by its numeric prefix.

Effects: fail, alloc.

### `sqlCompare`

```gizlang
function sqlCompare(a: Value, b: Value): i64
```

SQL comparison of two non-null values: a number against text compares the text as a number
when the whole text is one (as SQLite does for a numeric column against a text parameter),
booleans against numbers as 0/1; otherwise compareValues' total order. -2 when either is NULL.

Effects: fail, alloc.

### `timetzParts`

```gizlang
function timetzParts(text: string, declared: string, clock: i64): Vec<i64> throws DbError
```

A time with time zone as PostgreSQL 16 reads it (timetz_in) for a column or cast of `declared`, rounded to its
precision: [time of day in microseconds, seconds east of UTC]. A zone name needs a date; no zone is the session's (UTC).

Effects: fail, alloc.

### `timetzResultOf`

```gizlang
function timetzResultOf(op: string): string
```

The declared type of timetzApply's result for `op`.

Effects: fail.

### `timetzApply`

```gizlang
function timetzApply(op: string, args: Vec<Value>): Value throws DbError
```

An operator of time with time zone values (a text one is read as one): "key" (text that orders as timetz_cmp),
the comparisons, "part:FIELD" (EXTRACT; a third argument 2 asks date_part's double precision), "+i" and "-i" of an
interval (its time part, around the clock) and "at" of a date (date + timetz, timestamptz(date, timetz)).

Effects: fail, alloc.

### `temporalOfText`

```gizlang
function temporalOfText(text: string, unit: i64): Option<i64>
```

Text as a temporal value of `unit`.

Effects: fail, alloc.

### `arith`

```gizlang
function arith(op: string, a: Value, b: Value, dialect: Dialect): Value throws DbError
```

`a op b` for + - * / %, with NULL for a NULL operand. Integer overflow becomes a float (as
SQLite); division by zero is NULL in SQLite and MySQL, an error elsewhere. Dates and
intervals: date ± interval, timestamp ± interval, timestamp - timestamp (an interval), and
in PostgreSQL and Oracle date ± days and date - date (days). In SQL Server `+` on text
concatenates.

Effects: fail, alloc.

### `decimalOf`

```gizlang
function decimalOf(v: Value): Option<Dec>
```

An integer or decimal as a decimal.

Effects: fail, alloc.

### `decArith`

```gizlang
function decArith(op: string, x: Dec, y: Dec, dialect: Dialect): Value throws DbError
```

x op y of decimals in the dialect: Oracle's NUMBER (numberArith), or PostgreSQL's NUMERIC, where a result past
the decimal limits is an overflow (22003).

Effects: fail, alloc.

### `isMoney`

```gizlang
function isMoney(d: string): bool
```

Whether declared type `d` is PostgreSQL's money.

### `moneyOf`

```gizlang
function moneyOf(v: Value): Value throws DbError
```

`v` as PostgreSQL's money: a count of cents (a decimal at scale 2) within a signed 64-bit integer. Text takes
a leading or trailing minus or parentheses for a negative amount, a $ sign and thousands commas, and rounds
past the cents.

Effects: fail, alloc.

### `moneyRange`

```gizlang
function moneyRange(v: Value): Value throws DbError
```

Money arithmetic's result `v` as is, or 22003 past a signed 64-bit count of cents (PostgreSQL's cash_pl, cash_mul_flt8...).

Effects: fail, alloc.

### `moneyText`

```gizlang
function moneyText(v: Value): Option<string>
```

A money value as PostgreSQL prints it in the C locale: -$1,234.56. A result between cents (money divided by a
number) is cut toward zero, a real one rounded, as PostgreSQL computes them.

Effects: fail, alloc.

### `moneyWords`

```gizlang
function moneyWords(v: Value): string
```

PostgreSQL's cash_words: a money amount in English words.

Effects: fail, alloc.

### `castTo`

```gizlang
function castTo(v: Value, ty: string, dialect: Dialect): Value throws DbError
```

CAST(v AS ty). Text to numbers reads the numeric prefix in SQLite and the whole text
elsewhere (an error when it is not one); numbers to integers truncate in SQLite and round
half away from zero elsewhere.

Effects: fail, alloc.

### `charLimit`

```gizlang
function charLimit(declared: string): i64
```

The most characters a declared type holds: n of VARCHAR(n), CHAR(n) and their spellings
(VARCHAR2(n CHAR), NVARCHAR(n), CHARACTER VARYING(n)), 1 for a bare CHAR, -1 for no limit.

Effects: fail, alloc.

### `toDecimal`

```gizlang
function toDecimal(v: Value, ty: string, what: string): Value throws DbError
```

A value as a decimal of the declared type `ty` (`what` names it in errors): rounded half away
from zero to its scale, and no more integer digits than its precision allows (22003).

Effects: fail, alloc.

### `decimalAt`

```gizlang
function decimalAt(v: Value, scale: i64, precision: i64, what: string): Value throws DbError
```

`v` as a decimal at `scale` (-1: its own) with at most `precision` digits (0: any).

Effects: fail, alloc.

### `decimalText`

```gizlang
function decimalText(d: Dec, dialect: Dialect): string
```

A decimal as text: at its scale, or without trailing zeros where the dialect's numbers keep none (Oracle).

Effects: fail, alloc.

### `floatInteger`

```gizlang
function floatInteger(x: f64, dialect: Dialect): Option<i64>
```

The integer a cast of the float X gives in DIALECT, or none when it is NaN or past 64 bits (the cast fails): PostgreSQL
rounds to the nearest, a half to the even one (rint), SQLite's affinity cuts. The column kernel (vm.giz castKernel) and the
scalar cast both take it.

Effects: fail.

### `roundTo`

```gizlang
function roundTo(x: f64, digits: i64): f64
```

`x` rounded half away from zero at `digits` after the point (negative: before it).

Effects: fail, alloc.

### `keepsInt`

```gizlang
function keepsInt(k: i64): bool
```

Whether keeps() code `k` keeps integers.

### `keeps`

```gizlang
function keeps(col: ColumnDef, dialect: Dialect): i64
```

Which values `assign` stores into `col` unchanged, so a bulk insert decides per column once
(assign per value cost 580 instructions for an int into an int column; a text column also
read its declared type per value): 1 int, KEEP_INT4 and KEEP_INT2 int within that width, 2 float, 3 text, 4 boolean, 5 decimal, 6 date, KEEP_DECIMAL + 1000 s + p decimal of scale s,
KEEP_TEXT_WITHIN + n
text of at most n bytes for a column of at most n characters, 0 none.

Effects: fail, alloc.

### `kept`

```gizlang
function kept(v: Value, k: i64): bool
```

Whether `assign` returns `v` itself for a column whose keeps() is `k`.

Effects: fail, alloc.

### `assignment`

```gizlang
function assignment(col: ColumnDef, dialect: Dialect): Assignment
```

How a value is made fit for column COL in DIALECT.

Effects: fail, alloc.

### `assign`

```gizlang
function assign(v: Value, col: ColumnDef, dialect: Dialect): Value throws DbError
```

V made fit for column COL by the assignment rules of DIALECT.

Effects: fail, alloc.

### `assignAs`

```gizlang
function assignAs(v: Value, col: ColumnDef, a: Assignment, dialect: Dialect): Value throws DbError
```

assign with the column's Assignment. An integer stays within its column's intWidth, as
PostgreSQL's smallint and integer do.

Effects: fail, alloc.

### `jsonInput`

```gizlang
function jsonInput(x: string, declared: string): Value throws DbError
```

JSON input as PostgreSQL reads it for the declared type: json keeps the text once it parses;
jsonb is its canonical text (keys by length then bytes, the last of equal keys, ", " and ": "
between items, numbers as numeric); jsonpath is the path's canonical text.

Effects: fail, alloc.

### `renderWorkBytes`

```gizlang
function renderWorkBytes(v: Value, declared: string, dialect: Dialect, limit: i64): Option<i64>
```

Pre-allocation bound for render's UTF-8 text. Ordinary text and BYTEA are exact; numeric
and temporal widths are bounded without rendering. Tagged intervals additionally cover
intervalParts' input-dependent parsing workspace. The caller separately admits simultaneous
rendered text, UTF-8, row/frame buffers and their copy-on-write overlap. None refuses the
supplied credit or an invalid decimal scale; no payload-sized temporary is allocated here.

Effects: fail, alloc.

### `render`

```gizlang
function render(v: Value, declared: string, dialect: Dialect): Option<string>
```

A value as the dialect's client reads it: SQLite prints reals with 15 significant digits
(1.0, 0.3), PostgreSQL with the shortest exact digits; booleans are 1/0, t/f or TRUE/FALSE;
decimals print at their scale outside SQLite and Oracle (whose NUMBER keeps no trailing zeros). NULL is none.

Effects: fail, alloc.

### `bareFraction`

```gizlang
function bareFraction(t: string): string
```

`t`, a number as text, without the 0 before its point: 0.4 is .4, -0.4 is -.4.

Effects: fail, alloc.

### `floatDigits`

```gizlang
function floatDigits(dialect: Dialect): i64
```

PostgreSQL's extra_float_digits: (Dialect.dateOrder / 16) % 64 holds 1 - n for n <= 0, and 0 for 1 and up; IntervalStyle
is Dialect.dateOrder / 1024.

Effects: fail.

### `pgFloatText`

```gizlang
function pgFloatText(x0: f64, real: bool, digits: i64): string
```

A finite double precision (or, with `real`, a real) as PostgreSQL's float8out and float4out write it: with
`digits` (extra_float_digits) above 0 the fewest digits that read back as the value, in plain notation for
decimal exponents from -4 to below 15 (6 for a real); else printf's %g with 15 (6) + digits significant digits.

Effects: fail, alloc.

### `oracleBinaryText`

```gizlang
function oracleBinaryText(x0: f64, single: bool): string
```

Oracle's TO_CHAR of a BINARY_FLOAT (`single`) or BINARY_DOUBLE without a format: 9 (17) significant digits, a zero
dropped from the end but one decimal kept, and a three-digit exponent: 1.5E+000, 3.33333343E-001.

Effects: fail, alloc.

### `gText`

```gizlang
function gText(x: f64, p: i64): string
```

C's printf("%.<p>g"): `p` significant digits without trailing zeros, in exponent notation when the
decimal exponent is below -4 or at least `p`. The digits are the exact value's, rounded half to even.

Effects: fail, alloc.

### `trimFraction`

```gizlang
function trimFraction(s: string): string
```

`s` without the zeros after its point (and the point when none is left); a number with an exponent stays.

Effects: fail, alloc.

### `floatText`

```gizlang
function floatText(x: f64, short: bool): string
```

A real as text: SQLite's 15 significant digits when `short` (Dialect.affinity), else the shortest exact form.

Effects: fail, alloc.

### `vectorText`

```gizlang
function vectorText(v: Vec<f32>): string
```

A vector as [1,0.5,-2], each element with the fewest digits that read back as its f32.

Effects: fail, alloc.

### `sparseText`

```gizlang
function sparseText(v: Vec<f32>): string
```

A vector as pgvector's sparsevec text: {1:0.5,3:2}/5, its nonzero elements by 1-based index, then its dimensions.

Effects: fail, alloc.

### `parseTemporal`

```gizlang
function parseTemporal(text: string): Option<i64>
```

Microseconds since the epoch of 'YYYY-MM-DD', 'YYYY-MM-DD HH:MM[:SS[.f]]' (T or space),
with an optional Z or ±HH[:MM] offset (converted to UTC), or of a SQLite julian day / unix
number is not read here.

Effects: fail, alloc.

### `timeZoneOf`

```gizlang
function timeZoneOf(name: string, iso: bool): TimeZone throws DbError
```

The zone NAME names: an abbreviation or offset zoneSeconds reads (`iso` as there), else a tz database zone.

Effects: fail, alloc.

### `sessionZone`

```gizlang
function sessionZone(v: string): Option<string>
```

The zone that SET TimeZone's value `v` names, as Dialect.zone keeps it ("" is UTC), or none when it names no zone.
A number is hours east (+10, -1.5), as PostgreSQL's check_timezone reads it; it is kept as PostgreSQL shows it, a POSIX zone
named by its offset ("<-01:30>+01:30"). Other text is a POSIX zone, an abbreviation or a zone name, which timeZoneOf
reads.

Effects: fail, alloc.

### `sessionTimeZone`

```gizlang
function sessionTimeZone(dialect: Dialect): TimeZone
```

The session's zone (Dialect.zone).

Effects: fail, alloc.

### `regionUnit`

```gizlang
function regionUnit(name: string): Option<i64>
```

The unit of a value in the tz database region NAME (any case), or none when there is no such region.

Effects: fail, alloc.

### `regionName`

```gizlang
function regionName(u: i64): string
```

The tz database name of a region unit as the database spells it ("Asia/Seoul"), "" for a fixed zone.

Effects: fail, alloc.

### `unitZone`

```gizlang
function unitZone(u: i64): TimeZone
```

The zone of a zoned unit.

Effects: fail, alloc.

### `unitEast`

```gizlang
function unitEast(u: i64, us: i64): i64
```

Seconds east of UTC in the zone of unit `u` at the instant `us`.

Effects: fail, alloc.

### `unitAbbreviation`

```gizlang
function unitAbbreviation(u: i64, us: i64): string
```

The abbreviation of a region unit's zone at the instant `us` (KST, PDT), "" for a fixed zone.

Effects: fail, alloc.

### `sessionUnit`

```gizlang
function sessionUnit(dialect: Dialect): i64
```

The unit of the session's zone: Oracle's SESSIONTIMEZONE.

Effects: fail, alloc.

### `zoneUnitOf`

```gizlang
function zoneUnitOf(spec: string, dialect: Dialect): Option<i64>
```

The zone unit an Oracle time zone name designates: a region (Asia/Seoul), a signed offset (+05:30), LOCAL or DBTIMEZONE;
none when no such zone exists.

Effects: fail, alloc.

### `oracleZone`

```gizlang
function oracleZone(spec: string, dialect: Dialect): Option<string>
```

The Dialect.zone that ALTER SESSION SET TIME_ZONE = spec gives ("" for the database zone), or none for no such zone.

Effects: fail, alloc.

### `oracleOffset`

```gizlang
function oracleOffset(east: i64): string
```

Oracle's text of an offset: +05:30.

Effects: fail, alloc.

### `zonedLocal`

```gizlang
function zonedLocal(local: i64, zone: i64): Value
```

A timestamp's wall time `local` read in the zone of unit `zone`, as a zoned value (Oracle's FROM_TZ).

Effects: fail, alloc.

### `zonedText`

```gizlang
function zonedText(text: string, dialect: Dialect): Option<Value> throws DbError
```

A timestamp's text with a zone after its time ("2021-05-07 13:04:05 +02:00", "... 13:04:05 Asia/Seoul"): the zoned
value; none when the text names no zone.

Effects: fail, alloc.

### `weekdays`

```gizlang
function weekdays(): Vec<string>
```

The days of the week by their full names, Sunday first (a function: reading a module Vec is an effect).

Effects: fail, alloc.

### `isInterval`

```gizlang
function isInterval(text: string): bool
```

Whether a value is an interval: \u0003months:days:microseconds.

Effects: fail.

### `interval`

```gizlang
function interval(months: i64, days: i64, us: i64): string
```

The stored text of an interval of MONTHS, DAYS and US microseconds.

Effects: fail, alloc.

### `intervalParts`

```gizlang
function intervalParts(text: string): Vec<i64>
```

The months, days and microseconds of a stored interval TEXT.

Effects: fail, alloc.

### `parseInterval`

```gizlang
function parseInterval(text: string): Option<string>
```

An interval's text read as PostgreSQL's interval_in does, None when it does not read.

Effects: fail, alloc.

### `intervalTypmod`

```gizlang
function intervalTypmod(t: string): Vec<i64>
```

The range and precision of an interval type name: INTERVAL, INTERVAL(2), INTERVAL DAY TO SECOND(3).

Effects: fail, alloc.

### `intervalText`

```gizlang
function intervalText(text: string): string
```

An interval as PostgreSQL prints it (EncodeInterval, IntervalStyle postgres): '1 year 2 mons -3 days +04:05:06'; a
part after a negative one shows its + sign.

Effects: fail, alloc.

### `styledInterval`

```gizlang
function styledInterval(text: string, style: i64): string
```

An interval in IntervalStyle `style`: 0 postgres, 1 postgres_verbose, 2 sql_standard, 3 iso_8601 (EncodeInterval).

Effects: fail, alloc.

### `addMonths`

```gizlang
function addMonths(days: i64, months: i64): i64
```

Adds months to a day number, clamping the day to the month's end (Jan 31 + 1 month = Feb 29).

Effects: fail.

### `dayInRange`

```gizlang
function dayInRange(days: i64): bool
```

Whether day number `days` (from 1970-01-01) is a day PostgreSQL keeps whose microseconds fit in 64 bits:
4714-11-24 BC (Julian day 0) to about 294246 AD.

Effects: fail.

### `outOfRange`

```gizlang
function outOfRange(): i64
```

The microseconds a temporal result past the 64-bit range takes; arith turns it into "timestamp out of range".

Effects: fail.

### `typeLabel`

```gizlang
function typeLabel(v: Value): string
```

A value's type as an operator error names it.

Effects: fail.

### `dateDifference`

```gizlang
function dateDifference(a: Value, b: Value, days: bool, dialect: Dialect): Value
```

Oracle's difference of two dates or timestamps: the days between as a NUMBER (`days`, DATE - DATE), else an INTERVAL DAY TO SECOND.

Effects: fail, alloc.

### `arrayLower`

```gizlang
function arrayLower(v: Value): i64
```

The first subscript of an array value: 1 unless its text starts with [lo:hi]=.

Effects: fail, alloc.

### `arrayBody`

```gizlang
function arrayBody(s: string): string
```

The {...} part of array text S: a lower bound other than 1 is written first, as in [0:1]={a,b}.

Effects: fail, alloc.

### `arrayElements`

```gizlang
function arrayElements(v: Value): Vec<Value>
```

The elements of the array value V.

Effects: fail, alloc.

### `arraySlices`

```gizlang
function arraySlices(v: Value, k: i64): Vec<Value>
```

FOREACH ... SLICE k's items: the elements (k = 0), or the arrays of the last k dimensions, in storage order.

Effects: fail, alloc.

### `arrayShape`

```gizlang
function arrayShape(v: Value): Vec<Vec<i64>>
```

The shape of an array value: [lower bounds, lengths], one of each per dimension; none for an empty array.

Effects: fail, alloc.

### `arrayCompare`

```gizlang
function arrayCompare(a: Value, b: Value, numeric: bool): i64
```

PostgreSQL's array ordering (array_cmp): element by element, a NULL after any value, then the shorter array first.
`numeric` compares the elements as numbers.

Effects: fail, alloc.

### `arrayLiteral`

```gizlang
function arrayLiteral(items: Vec<Value>, dialect: Dialect): string
```

A PostgreSQL array literal of `items`: {1,2}, {"a b",NULL}. An element is quoted when it is empty,
NULL as text, or holds a space, a comma, a brace, a quote or a backslash.

Effects: fail, alloc.

### `arrayItem`

```gizlang
function arrayItem(v: Value, dialect: Dialect): string
```

One element of an array literal, quoted as arrayLiteral says.

Effects: fail, alloc.

### `isArrayType`

```gizlang
function isArrayType(declared: string): bool
```

Whether a declared type is an array: INT[], TEXT[][], INTEGER ARRAY.

Effects: fail, alloc.

### `paddedArray`

```gizlang
function paddedArray(v: Value, width: i64, dialect: Dialect): Value
```

Array literal `v` with each element padded with spaces to `width` characters, as a char(n)[] value is stored.

Effects: fail, alloc.

### `arrayElementType`

```gizlang
function arrayElementType(declared: string): string
```

The element type of an array type: INT[] is INT.

Effects: fail, alloc.

### `integerOverflow`

```gizlang
function integerOverflow(name: string): DbError
```

22003: a result past the range of NAME, "integer" or "bigint".

Effects: fail, alloc.

### `intervalOverflow`

```gizlang
function intervalOverflow(): DbError
```

22008: an interval result past the range of its fields.

Effects: fail, alloc.

### `zeroStep`

```gizlang
function zeroStep(): DbError
```

22023: a series with a step of zero.

Effects: fail, alloc.

### `rangeSubtype`

```gizlang
function rangeSubtype(declared: string): string
```

The element type of a range or multirange type: int4range and int4multirange are int4; "" for any other type.

Effects: fail, alloc.

### `isRangeType`

```gizlang
function isRangeType(declared: string): bool
```

Whether DECLARED names a range type.

Effects: fail, alloc.

### `rangeInput`

```gizlang
function rangeInput(text: string, sub: string, dialect: Dialect): Value throws DbError
```

Text read as a range of `sub` (a cast or a column of a range type), canonical.

Effects: fail, alloc.

### `rangeConstruct`

```gizlang
function rangeConstruct(lo: Value, hi: Value, bounds: string, sub: string, dialect: Dialect): Value throws DbError
```

int4range(lo, hi [, '[)']) and the other range constructors: a NULL bound is unbounded.

Effects: fail, alloc.

### `floatOrderBits`

```gizlang
function floatOrderBits(x: f64): u64
```

The bits of float X as an unsigned number that orders as X does: negatives flipped, positives with the sign set.

Effects: fail.

### `rangeOp`

```gizlang
function rangeOp(op: string, a: Value, b: Value, sub: string, dialect: Dialect): Value throws DbError
```

A range operator or function on ranges of `sub`: @>, <@, &&, <<, >>, &<, &>, -|-, +, *, -, =, <>, <, <=, >, >=,
range_merge, lower, upper, isempty, lower_inc, upper_inc, lower_inf, upper_inf. NULL in gives NULL out.

Effects: fail, alloc.

### `isMultirangeType`

```gizlang
function isMultirangeType(declared: string): bool
```

Whether a declared type is a multirange type (int4multirange, nummultirange, ...).

Effects: fail, alloc.

### `multirangeInput`

```gizlang
function multirangeInput(text: string, sub: string, dialect: Dialect): Value throws DbError
```

Text read as a multirange of `sub`, canonical; a range's text is the multirange of that range.

Effects: fail, alloc.

### `multirangeConstruct`

```gizlang
function multirangeConstruct(a: Vec<Value>, sub: string, dialect: Dialect): Value throws DbError
```

int4multirange(r1, r2, ...) and the other multirange constructors; a NULL range is an error.

Effects: fail, alloc.

### `temporalSeriesCount`

```gizlang
function temporalSeriesCount(start: Value, stop: Value, step: Value, most: i64, dialect: Dialect): i64 throws DbError
```

How many values generate_series(start, stop, step) gives for a date or time `start` and an
interval `step`: start, then each value plus step, while not past stop (PostgreSQL adds the step
again each time, so a month step stays on a clamped day). An infinite stop gives `most`.

Effects: fail, alloc.

### `nameText`

```gizlang
function nameText(x: string): string
```

Text as a PostgreSQL name: its first 63 bytes, without a character cut in two.

Effects: fail, alloc.

### `rint`

```gizlang
function rint(x: f64): f64
```

rint: the nearest integer, a half to the even one.

Effects: fail.

### `intervalValue`

```gizlang
function intervalValue(v: Value): bool
```

Whether `v` is an interval value.

Effects: fail.

### `intervalAdd`

```gizlang
function intervalAdd(total: Value, v: Value): Value
```

sum(interval)'s step: `total` (NULL before the first) plus `v`; the out-of-range marker once it overflows.

Effects: fail, alloc.

### `intervalAverage`

```gizlang
function intervalAverage(total: Value, count: i64): Value
```

avg(interval): the sum divided by the count, as interval_div does it.

Effects: fail, alloc.

### `intervalNegated`

```gizlang
function intervalNegated(text: string): Value throws DbError
```

interval_um: -`text`, or "interval out of range" for a field at its type's minimum.

Effects: fail, alloc.

### `xmlInput`

```gizlang
function xmlInput(text: string, document: bool): string throws DbError
```

A text checked as XML content or a document (xml.giz): 2200N or 2200M with PostgreSQL's message.

Effects: fail, alloc.

### `bitDeclared`

```gizlang
function bitDeclared(declared: string): i64
```

PostgreSQL bit strings are stored as text of 0 and 1: 1 for BIT and BIT(n), 2 for VARBIT and BIT VARYING(n), else 0.

Effects: fail, alloc.

### `bitLimit`

```gizlang
function bitLimit(declared: string): i64
```

n of BIT(n) or BIT VARYING(n), -1 for none.

Effects: fail, alloc.

### `bitText`

```gizlang
function bitText(input: string): string throws DbError
```

The bits of bit string input: binary digits (after an optional b or B), or hexadecimal ones after x or X (22P02 for another character).

Effects: fail, alloc.

### `bitAssign`

```gizlang
function bitAssign(input: string, declared: string): Value throws DbError
```

A bit string stored in a column of `declared` (assignment and input): BIT(n) takes exactly n bits (22026), a bare BIT
one; BIT VARYING(n) at most n (22001).

Effects: fail, alloc.

### `textParameter`

```gizlang
function textParameter(v: Value, declared: Type, dialect: Dialect): Option<string> throws string
```

A value as a parameter of a store whose transport is text: NULL is none, and bytes are refused (they have no text form there). `declared` is the parameter's type; `Value.declared()` when the caller has none.

Effects: fail, alloc.

### `numericFormatOverflow`

```gizlang
function numericFormatOverflow(): DbError
```

PostgreSQL's 22003 for a value past the NUMERIC limits.

Effects: fail, alloc.

## Methods

### `TimeZone.eastAt`

```gizlang
function TimeZone.eastAt(self: TimeZone, us: i64): i64
```

Seconds east of UTC at the instant `us` (microseconds since the epoch).

Effects: fail.

### `TimeZone.utcOf`

```gizlang
function TimeZone.utcOf(self: TimeZone, local: i64): i64
```

The instant of the local time `local` in the zone. A local time that a transition skips or repeats takes the
later instant, as PostgreSQL's DetermineTimeZoneOffset does: the offset before a spring-forward gap, the one after
a fall-back overlap.

Effects: fail.

## Constants

### `KEEP_DATE`

```gizlang
const KEEP_DATE: i64 = 6
```

keeps() of a DATE column: a COPY reader reads YYYY-MM-DD as a date (copy.giz rawField).

### `KEEP_DECIMAL`

```gizlang
const KEEP_DECIMAL: i64 = 2000000
```

keeps() of a DECIMAL(p, s) column is KEEP_DECIMAL + 1000 s + p (p 0 when unwritten): a COPY reader
reads a plain decimal of at most s fraction digits at scale s (copy.giz rawField).

### `KEEP_INT4`

```gizlang
const KEEP_INT4: i64 = 7
```

keeps() of an integer column of 4 or 2 bytes (intWidth): an integer within that width.

### `KEEP_INT2`

```gizlang
const KEEP_INT2: i64 = 8
```

keeps() of an integer column of 2 bytes.

### `KEEP_TIMESTAMP`

```gizlang
const KEEP_TIMESTAMP: i64 = 9
```

keeps() of a TIMESTAMP column: a COPY reader reads YYYY-MM-DD HH:MM:SS as a timestamp (copy.giz rawField); per value
the assign path looked for a zone and a fraction, a fifth of a ClickBench parse.

