# Standard Library Reference

OxigenLang's standard library is a set of `.oxi` modules that ship with the
interpreter. Import one with `introduce`:

```oxi
introduce math
println(math.sqrt(16))   // 4
```

Or pull specific names into scope:

```oxi
introduce {sqrt, abs} from math
println(sqrt(16))
```

Structs must be imported by name — `introduce {Parser} from parse_args` — since
a struct is not constructible through a module namespace. See
[imports.md](https://www.oxigenlang.org/docs/imports/) for the full import syntax.

One page per module, each documenting **every** callable function with
examples:

## Data and text

| Module | What it covers |
|--------|----------------|
| [strings](https://www.oxigenlang.org/docs/stdlib/strings/) | split, join, trim, case, search, pad |
| [array](https://www.oxigenlang.org/docs/stdlib/array/) | map/filter/reduce, folds, search, sort, group, `pmap` |
| [sets](https://www.oxigenlang.org/docs/stdlib/sets/) | union, intersection, difference, subset tests |
| [math](https://www.oxigenlang.org/docs/stdlib/math/) | arithmetic, rounding, trig, logs, gcd/lcm, `PI`/`E`/`TAU` |
| [regex](https://www.oxigenlang.org/docs/stdlib/regex/) | match, find, captures, replace, split (Rust regex syntax) |
| [json](https://www.oxigenlang.org/docs/stdlib/json/) | parse/stringify, files, dotted paths, merging |
| [toml](https://www.oxigenlang.org/docs/stdlib/toml/) | same API as `json`, for TOML documents |
| [encoding](https://www.oxigenlang.org/docs/stdlib/encoding/) | base64, hex, URL percent-encoding |
| [hash](https://www.oxigenlang.org/docs/stdlib/hash/) | SHA-256, SHA-1, MD5 hex digests |

## System

| Module | What it covers |
|--------|----------------|
| [io](https://www.oxigenlang.org/docs/stdlib/io/) | read/write/append files, console input |
| [os](https://www.oxigenlang.org/docs/stdlib/os/) | run commands, background processes, signals, environment, directories |
| [path](https://www.oxigenlang.org/docs/stdlib/path/) | join, split, normalize, `is_within` containment check |
| [time](https://www.oxigenlang.org/docs/stdlib/time/) | timestamps, sleep, monotonic durations |
| [datetime](https://www.oxigenlang.org/docs/stdlib/datetime/) | UTC calendar dates, formatting, parsing |
| [random](https://www.oxigenlang.org/docs/stdlib/random/) | random ints/floats/bools, `choice`, `seed` |
| [env](https://www.oxigenlang.org/docs/stdlib/env/) | load a `.env` file into a map |
| [parse_args](https://www.oxigenlang.org/docs/stdlib/parse-args/) | command-line flag parsing |
| [channel](https://www.oxigenlang.org/docs/stdlib/channel/) | pass messages between `diverge` tasks, in order |

## Network

| Module | What it covers |
|--------|----------------|
| [net](https://www.oxigenlang.org/docs/stdlib/net/) | HTTP client, streaming HTTP, TCP and UDP sockets |
| [api](https://www.oxigenlang.org/docs/stdlib/api/) | HTTP server: routing, JSON and HTML responses, static files, the accept loop |

## C interop

| Module | What it covers |
|--------|----------------|
| [ffi](https://www.oxigenlang.org/docs/stdlib/ffi/) | call C libraries by signature: structs, pointers, variadics, callbacks |

## Language support

| Module | What it covers |
|--------|----------------|
| [result](https://www.oxigenlang.org/docs/stdlib/result/) | helpers for the `Error \|\| Value` system |
| [test](https://www.oxigenlang.org/docs/stdlib/test/) | `expect(...)` matchers used by `oxigen test` |
| [ansi](https://www.oxigenlang.org/docs/stdlib/ansi/) | terminal colour, modifiers, cursor control |

---

## Conventions across the library

**Errors.** Two kinds show up. A *catchable* error is an ordinary value you can
inspect (`math.factorial(-1)`, `json.parse` on bad input). A *terminal* error
halts the program (most of [net](https://www.oxigenlang.org/docs/stdlib/net/), a missing file in [io](https://www.oxigenlang.org/docs/stdlib/io/)). Turn
the second into the first by normalizing the call:

```oxi
r := <type<Error> || <Value>>(io.read_file("maybe.txt"))
option {
    is_error(r) -> { println("failed: {r.msg}") }
    { println(r.value) }
}
```

[result](https://www.oxigenlang.org/docs/stdlib/result/) has the helpers that make chains of these readable.

**A module's API is what it does not hide.** Top-level bindings are public by
default; a helper marked `hide fun` is callable only inside its own file
(`array`'s `_min_index_by` and `_remove_at`, for instance). Struct fields take
the same keyword inside the struct body.

**Reach for dot access on a key you know is there.** `resp.status`,
`data.information`, `john.info.job` — reading *or* writing. A mistyped key
errors instead of silently reading `None`, which is the point:

```oxi
resp := net.get(url)
println(resp.status)         // always present — dot
println(resp.stauts)         // error: key 'stauts' not found on map
```

Brackets are for the three cases dot cannot serve: a key that may be **absent**
(`req.query["page"]`), a key held in a **variable** (`users[id]`), and a key
that is not an identifier (`headers["content-type"]`). Bracket reads answer
`None` for a missing key, so they are also the form to use when absence is the
thing you are testing. Full rules in [data_types.md](https://www.oxigenlang.org/docs/data-types/).

**Maps and arrays are shared references.** `insert`, `remove`, `push`, and
every `*_in`/`merge`/`set_where` function in [json](https://www.oxigenlang.org/docs/stdlib/json/) and
[toml](https://www.oxigenlang.org/docs/stdlib/toml/) modify the value you pass and return that same value.
Round-trip through `stringify`/`parse` for a copy of a map;
`array.slice(a, 0, len(a))` copies an array.

**Strings are immutable**, and the [array](https://www.oxigenlang.org/docs/stdlib/array/) module's own functions
(`map`, `filter`, `unique`, …) build a new array rather than editing yours.

**Sockets and streams use handles.** [net](https://www.oxigenlang.org/docs/stdlib/net/) hands back an opaque number;
always `close` it.

---

## Where the rest of the language is documented

| Page | Contents |
|------|----------|
| [builtins.md](https://www.oxigenlang.org/docs/builtins/) | global functions — `len`, `push`, `keys`, `range`, `type`, `has`, … |
| [imports.md](https://www.oxigenlang.org/docs/imports/) | `introduce` syntax, namespacing, local modules |
| [type_system.md](https://www.oxigenlang.org/docs/type-system/) | type annotations, `Error \|\| Value` |
| [angle_forms.md](https://www.oxigenlang.org/docs/angle-forms/) | `<fail>`, `<log>`, `<type<...>>` and friends |
| [concurrency.md](https://www.oxigenlang.org/docs/concurrency/) | `diverge`, `converge`, share-nothing threading |
| [testing.md](https://www.oxigenlang.org/docs/testing/) | the `oxigen test` runner |

The sources are worth reading — every module is plain Oxigen in `stdlib/`.