# std — the Flash standard library

The standard library is written in Flash. Consumers import it as a single
named module (`use core`) and reach the submodules through it
(`core.mem.eql`, `core.list.List`, …). The surface mirrors Zig's `std`
spellings on purpose: a facade can re-route a call site between the two
implementations without touching it.

One confinement rule shapes the whole tree: `base` is the only module that
may import Zig's `std`. Every other file is pure Flash and imports only
`base` and its sibling modules, so the toolchain dependency stays behind a
single door.

## Modules

| Module | What it is |
| --- | --- |
| `core` | The root — nothing but re-exports; one line per submodule. |
| `base` | The Zig interop shim — the one permitted `use std`; an enumerated bill of materials that grows only with the module that needs it. |
| `mem` | Slice and memory primitives — equality, search, copy, fill, ordering, a deliberately stable sort, explicit-endian integer codecs, and byte views of memory. |
| `list` | `List(T)` — the dynamic array, mirroring Zig's unmanaged ArrayList surface. |
| `fmt` | String formatting and integer parsing — comptime-checked format strings, allocating or into a caller buffer, overflow-checked accumulation. |
| `math` | Integer bounds, computed exactly from the type's own bit width. |
| `arena` | The arena allocator — a real `Allocator` v-table in Flash; everything allocated through it is released by one `deinit`. |
| `json` | A minimal RFC 8259 JSON value tree — strict `parse` and compact `stringify`, integer-fidelity numbers, arena-oriented allocation. |

## Where the documentation lives

Each module's documentation is the comment block at the top of its file:
what the module provides, the contract it keeps, and the design choices
that are load-bearing. Public functions carry their own doc comments at
the definition. The in-module `test` blocks double as usage examples —
including the induced-allocation-failure sweeps that prove every
out-of-memory path surfaces as an error.

## Running the tests

```sh
zig build test-std    # transpile and run the standard library's test suite
```

The std sources are also part of the compiler's fixpoint corpus, so every
release proves they transpile deterministically.