# Standard library expansion 1

These are additions to the restored Linux runtime, not recovered historical commands. No file, DB or network permission is required. Run `build/vanilla1 run examples/stdlib.v`; regression entry points are `make test-stdlib`, `make test-stdlib-sanitize`, and the normal `make test` / `make test-sanitize` suites.

## Commands

All destinations must be declared with `var`. `$dest` may be the same variable as any source. Native arrays contain strings; JSON arrays are a separate typed value.

| Command | Meaning |
|---|---|
| `array sort $dest $source numeric` | Stable ascending finite binary64 decimal sort. Preserve original text spelling and order of equal numeric values. |
| `array sort $dest $source lexical` | Stable ascending byte-string sort, case-sensitive and locale-independent. |
| `array reverse $dest $source` | Copy in reverse order. |
| `array slice $dest $source start count` | Copy zero-based range; require `0 <= start <= length` and `0 <= count <= length-start`. No negative indices, clipping or implicit end. |
| `array find $dest $source value` | First exact byte-string match index, or `-1`. No numeric coercion. |
| `array remove $dest $source index` | Copy without the element at a valid zero-based index. Empty/out-of-bounds is an error. |
| `array unique $dest $source` | Keep first occurrence of each exact string, preserving order. `2`, `02`, and `2.0` are distinct. |
| `json append $items value` | Append one value to a JSON array. |
| `json insert $items index value` | Insert before zero-based index; index equal to length appends. |
| `json remove $items index` | Remove one element at a valid zero-based index. |
| `json length $dest $source` | Top-level array element or object key count; reject scalars. |
| `json contains $dest $items value` | Deep-equal array membership, returning `1` or `0`. |
| `json merge $dest $left $right left` | Shallow object union; retain left value for duplicate keys. |
| `json merge $dest $left $right right` | Shallow object union; replace duplicate values with right values. |
| `json merge $dest $left $right error` | Reject every duplicate key, even if its values are equal. |
| `text contains $dest text needle` | Case-sensitive byte substring predicate. |
| `text startswith $dest text prefix` | Case-sensitive byte prefix predicate. |
| `text endswith $dest text suffix` | Case-sensitive byte suffix predicate. |
| `text padleft $dest text width padding` | Pad on the left to the requested byte width. |
| `text padright $dest text width padding` | Pad on the right to the requested byte width. |
| `number valid $dest value` | Return `1` for a complete finite decimal binary64 conversion, otherwise `0`. Type misuse still raises an error. |
| `number convert $dest value` | Normalize finite decimal input to shortest round-trip general-format text. |
| `number format $dest value places` | Fixed-point text with exactly 0–100 fractional decimal places. |

There are 20 new operation names; the table separates the sort modes and merge policies. `build/stdlib/commands.json` is the machine-readable inventory.

## Types and edge cases

JSON insertion and membership use the same value convention as existing `map set`: a JSON variable contributes its typed JSON value; an ordinary scalar variable or literal contributes a JSON **string**, even for literal `2`, `true` or `null`. Use `json parse $value 2` before `json append $items $value` for a number. Native array values are rejected. JSON equality compares nested values, treats integer `1` and floating `1.0` as equal, and keeps booleans and strings distinct. Merge is **not recursive**, not JSON Merge Patch, and does not interpret `null` as deletion. Object keys use existing deterministic serialization order.

Text predicates return `1` or `0`, with empty needles/prefixes/suffixes always matching. Text is byte-oriented, including embedded NUL from runtime values. Padding repeats a mandatory nonempty string and truncates its final repetition to the exact required byte count; it never truncates input when width is shorter. Width is 0–1048576. Multibyte padding can be cut inside a UTF-8 sequence: this is not grapheme-aware formatting.

New numeric helpers and numeric sort accept optional leading `+` or `-`, decimal point, and decimal exponent, with no surrounding whitespace. They reject trailing characters, hexadecimal syntax, NaN, infinity, overflow, and conversion underflow to zero. Representable subnormals (e.g. `5e-324`) are accepted. Input is rounded to IEEE binary64, so validation does not promise exact decimal representability. `number convert` may use exponent notation. `number format` uses a dot regardless of locale and rounds the **binary64 value, not an exact decimal number**: `2.675` with two places is `2.67`. Ties such as `2.5`/`3.5` at zero places produce `2`/`4` on the tested implementation. Negative zero, including a negative number rounded to zero, is rendered without a minus sign. These are not money/exact-decimal helpers.

New index/count/width/place operands accept finite decimal numbers only when their parsed value is an integer inside the documented bounds (so `2.0` and `2e0` are allowed).

## Copy, aliasing, atomic failure and limits

All new commands build a result before replacing the one destination. A normal error leaves that destination and all sources unchanged; JSON updates are copy-on-write immutable snapshots, including self-append/insert and function argument copies. Native array transforms produce copies. Aliasing a destination with a source is supported. A failed numeric sort never leaves a partially sorted source. Cached numeric state is replaced with fresh scalar/array/JSON state at commit.

The destination is swapped only after constructing a validated value; frame-budget validation rolls it back on any exception. Existing resource-limit errors remain fatal (uncatchable), not recoverable transactions. Output already emitted by earlier commands is not rolled back.

Existing limits continue to apply: 1 MiB scalar value or JSON storage, 2 MiB frame including arguments/live foreach snapshots and retained capacities, 16384 native array items / JSON nodes, and JSON depth 64. JSON storage overhead can hit the byte limit before the node limit. Padding checks width before allocation. Sort parses each numeric key once before comparison. Unique uses an ordered set of views into its bounded source rather than quadratic duplicate scans. JSON mutation/merge may temporarily hold bounded source and result copies, and the C++ library's transient allocation overhead is not an exact process-RSS quota. Sorting/membership/merge are bounded by data limits, not separately metered per-element execution steps. Allocation failure terminates execution as before.

## Compatibility

Legacy math/numeric parsing, number formatting, array create/push/get/set/pop/len, text commands (`find`, `substr`, etc.), JSON commands and `map` behavior are unchanged. In particular, legacy math may reject subnormals accepted by the new helpers; converting one does not change that historical policy.

**New reserved function and named-parameter names: `text` and `number`.** A prior program defining `function text`, `function number`, or a named parameter with either name now fails at load time. Rename those functions/parameters before upgrading. Local `var text number`, `$text`, and `$number` remain legal. Regression cases explicitly cover both rejection and permitted local names, and the pre-expansion executable is retained to demonstrate the compatibility delta. There is no attempt to silently reinterpret conflicting user functions.

All commands are arity/operation validated at load time, including dead code. Sort mode and merge policy are literal command options, not variable expressions.

## Verification and references

`tests/test_stdlib.py` uses bounded subprocesses and exact output/structured-error assertions, exercises every new operation, alias/copy behavior, invalid arguments/types, numeric cache replacement, finite values, bounds, UTF-8 byte widths, storage/frame/depth limits, reserved-name conflicts and the shipped example. It needs no remote SQL fixtures. `build/stdlib` retains baseline-red results, build logs, command exit codes, feature reports, complete regression logs, CGI output, and historical evidence. See `build/stdlib/verification.json` for executed results; do not infer a pass from this document alone.

A pre-existing browser-dashboard harness race was reproduced on the preserved pre-expansion ASan executable: after all browser interactions completed, slow browser teardown could outlast the demo's intentionally finite 1000-turn event loop, and the harness rejected its clean exit. The harness now accepts only a still-running process or exit 0 after the full interactions and final zero-client assertion; nonzero exits and sanitizer diagnostics still fail. Baseline/candidate failed evidence and the corrected runs are retained under `build/stdlib/dashboard-*`. This changed the test harness, not the dashboard application or networking runtime.

Primary API references consulted (not new dependencies):

```text
https://eel.is/c++draft/charconv.from.chars
https://eel.is/c++draft/charconv.to.chars
https://json.nlohmann.me/api/basic_json/operator_eq/
```

Implementation uses the installed C++17 `<charconv>` APIs and existing nlohmann JSON library. No encoding, UUID, website, production database, or remote SQL fixture changes are part of this expansion.