# gizmodel/sql/types/scalar

What every SQL function shares: the context it may read (Cx), the function value (Fn, Scalar) and the helpers that make and read argument values. func.giz and the fn*.giz modules use it.

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

## Types

### `Cx`

```gizlang
type Cx = { dialect: Dialect; now: i64; bits: u64; key: u64; }
```

What a function may read besides its arguments: the dialect, the statement's time
(microseconds since the epoch, one value for the whole statement as SQL requires) and, for a
volatile function, 64 random bits the caller draws for this call (distinct per row) and the session's secret
`key`, 64 bits it never shows, which make a value from the bits unguessable (uuid). Functions
are pure otherwise, so plans call them from every core.

- `dialect`: `M158.Dialect`
- `now`: `i64`
- `bits`: `u64`
- `key`: `u64`

### `Fn`

```gizlang
type Fn = (args: Vec<Value>, cx: Cx) => Value throws DbError effects {fail, alloc}
```

The implementation of a scalar function: its arguments and context to its value.

### `Scalar`

```gizlang
type Scalar = { fn: Fn; min: i64; max: i64; volatile: bool; vector: i64; }
```

A scalar function: its implementation, the argument counts it takes (max -1: any), whether
each call needs fresh random bits (random(), uuid()), and for a distance of two vectors the
metric a batch computes it by (db/core/vector.giz L2, COSINE, IP, or PRODUCT for the inner product
itself; -1 for other functions).

- `fn`: `(args: Vec<M143.Value>, cx: M163.Cx) => M143.Value throws M129.DbError effects { fail, alloc }`
- `min`: `i64`
- `max`: `i64`
- `volatile`: `bool`
- `vector`: `i64`

## Functions

### `some`

```gizlang
function some(fn: Fn, min: i64, max: i64): Option<Scalar>
```

A scalar function that is not volatile, with its argument counts.

Effects: fail.

### `volatile`

```gizlang
function volatile(fn: Fn, min: i64, max: i64): Option<Scalar>
```

A volatile scalar function (it needs fresh random bits), with its argument counts.

Effects: fail.

### `ok`

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

V as the result of a scalar function.

### `nul`

```gizlang
function nul(): Value throws DbError
```

The null value.

### `text`

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

The text value S.

### `int`

```gizlang
function int(n: i64): Value throws DbError
```

The integer value N.

### `float`

```gizlang
function float(f: f64): Value throws DbError
```

The float value F.

### `dateOut`

```gizlang
function dateOut(cx: Cx, days: i64): Value throws DbError
```

A date, timestamp or time a function returns: text in SQLite, whose dates are text.

Effects: fail, alloc.

### `tsOut`

```gizlang
function tsOut(cx: Cx, us: i64): Value throws DbError
```

The timestamp US (microseconds) as the dialect returns it: text in SQLite.

Effects: fail, alloc.

### `timeOut`

```gizlang
function timeOut(cx: Cx, us: i64): Value throws DbError
```

The time of day US (microseconds) as the dialect returns it: text in SQLite.

Effects: fail, alloc.

### `localNow`

```gizlang
function localNow(cx: Cx): i64
```

The statement clock as local time in the session's zone.

Effects: fail, alloc.

### `anyNull`

```gizlang
function anyNull(args: Vec<Value>): bool
```

Whether any of ARGS is null.

Effects: fail.

### `str`

```gizlang
function str(v: Value, cx: Cx): string
```

The text of a non-null value as string functions read it.

Effects: fail, alloc.

### `hasBlob`

```gizlang
function hasBlob(args: Vec<Value>): bool
```

Whether any of ARGS is a blob.

Effects: fail.

### `vectorOf`

```gizlang
function vectorOf(v: Value): Option<Vec<f32>>
```

The vector that V holds, or none.

Effects: fail, alloc.

### `charCount`

```gizlang
function charCount(s: string): i64
```

Characters (code points) of a text, as SQL's length and substr count them. Its bytes go to charsIn borrowed: bound to a
name they took a reference, two atomic writes to the string's header when threads share it (ClickBench Q27's length(URL)).

Effects: fail.

### `charsIn`

```gizlang
function charsIn(d: bytes, from: i64, to: i64): i64
```

The characters of UTF-8 D[FROM, TO): its bytes less its continuation bytes (10xxxxxx), eight at a time. A byte at a
time, ClickBench Q27's length(URL) was 79% of the query.

Effects: fail.

### `joined`

```gizlang
function joined(parts: Vec<string>, from: i64, to: i64): string
```

PARTS from FROM up to TO, joined.

Effects: fail, alloc.

### `charLen`

```gizlang
function charLen(t: bytes, i: i64): i64
```

The byte length of the UTF-8 character at I of T.

Effects: fail.

### `mix64`

```gizlang
function mix64(x0: u64): u64
```

SplitMix64's finalizer: a well-mixed 64-bit function of `x`, for random bits by position.

Effects: fail.

## Constants

### `PRODUCT`

```gizlang
const PRODUCT: i64 = 3
```

Scalar.vector of inner_product: the product, where IP (pgvector's <#>) is its negation.

