# Standard library

The standard library is the set of operations every program can use without
declaring them, such as `list.count(items)` and `temporal.in_zone(at, zone)`,
over the standard types, such as `Money`. A few are defined on the pages whose
features need them: [Values and types](/docs/values-and-types.md),
[Logic](/docs/logic.md) and [Dates and times](/docs/time-types.md).
This page collects the operations, and adds the ones real applications keep
reaching for. [Standard types](https://jadpo.dev/docs/types) lists every type.
[What's left out on purpose](/docs/the-standard-types.md#whats-left-out-on-purpose) says what to use
instead.

Operations are grouped into namespaces, each named for what it works on.
You always call an operation through its namespace: `list.count(items)`,
never `count(items)`.

| Namespace | Holds | Operations | Defined in |
|---|---|---|---|
| `list` | Operations on `List<T>` | 26 (4 from Values and types) | This page and [Collections](/docs/collections.md); inline functions in [Passing functions](/docs/passing-functions.md) |
| `set` | Operations on `Set<T>` | 7 | This page |
| `map` | Operations on `Map<K, V>` | 10 | This page |
| `range` | Operations on `Range<T>` and the ranges built on it | 3 | This page |
| `integer` | Operations on values built on `Int` | 5 (1 from Logic) | This page and [Logic](/docs/logic.md) |
| `decimal` | Operations on values built on `Decimal` | 13 (1 from Logic) | This page and [Logic](/docs/logic.md) |
| `money` | `Money`, its rates and discounts | 10 | This page |
| `units` | Physical quantities, `DataSize` and `Bitrate` | 3 | This page |
| `text` | Operations on text, and the contract's `parse`, `format` and `from` for every type | 21 | This page |
| `bytes` | Joining bytes | 1 | This page |
| `hash` | SHA-256 digests | 1 | This page |
| `encoding` | Bytes as text and back | 9 | This page |
| `crypto` | Encryption, passwords, signatures, message authentication | 10 | This page |
| `random` | Tokens, codes, shuffles; actions only | 5 | This page |
| `json` | One JSON document in memory, and large JSON lists through batches | 4 | This page; the batch forms in [Batches](/docs/batches-work-over-many-items.md) |
| `csv` | CSV files, read and written through batches | 2 | [Batches](/docs/batches-work-over-many-items.md) |
| `tsv` | TSV files, CSV's tab-separated form | 2 | [Batches](/docs/batches-work-over-many-items.md) |
| `json_lines` | JSON Lines files, one value per line | 2 | [Batches](/docs/batches-work-over-many-items.md) |
| `temporal` | Instants, dates, local times, zones, formats, recurrence | 24 (21 from Dates and times) | [Zones and local times](/docs/zones-and-local-times.md) and this page |
| `locale` | Choosing a supported locale | 1 | [Choosing a locale from a request](/docs/locales.md#choosing-a-locale-from-a-request) |
| `colour` | Converting `Colour` between spaces, contrast | 5 | This page |
| `web` | Building URLs, address blocks | 3 | This page |
| `semver` | Version ranges | 1 | This page |
| `media` | Fitting dimensions | 1 | This page |
| `markup` | Markdown and HTML, made safe | 3 | This page |

There are 171 operations in all: 28 defined on the Values and types,
Logic, and Dates and times pages, 8 file helpers defined with
[batches](/docs/batches-work-over-many-items.md), and 135
defined here. Operators are counted apart, in
[the standard operator table](/docs/the-standard-operator-table.md). Operations
on geometry and AI are counted on the [Geospatial](/docs/geospatial.md) and
[AI](/docs/ai.md) pages.

Every standard type also gets the same baseline of operations, generated
for it and not counted per type: construction, `text.parse`,
`text.format`, `text.from`, JSON, storage, `==` and order
([What every standard type can do](/docs/every-standard-type-meets-one-contract.md)).

The [design notes](https://github.com/jadpo-dev/jadpo/blob/main/docs/language/notes/19-standard-library.md) record why each part of
this page is the way it is, and [What is built](/docs/standard-library-built.md) says
which parts work today. One operation, `crypto.verify_totp`, isn't built
yet.

| Page | What it covers |
|---|---|
| [What every operation follows](/docs/what-every-operation-follows.md) | Every namespace follows the same rules, so a call you haven't seen before reads like one you have. |
| [All operations](/docs/standard-library-operations.md) | The sections below list every operation beyond the contract's baseline, with its signature, failures and SQL form, one section per namespace or group of types. |
| [The standard operator table](/docs/the-standard-operator-table.md) | Operators on standard types work by one fixed table rather than a library function per job, so `price * 20%` and `distance / 2h` read as they would on paper. |
| [Lists](/docs/lists.md) | A list holds items of one type in order, like an array in TypeScript, except that it never changes: every operation that changes a list gives you a new one. |
| [Sets](/docs/sets.md) | A set holds items of one type, each only once, and has no order your code can use. |
| [Maps](/docs/maps.md) | A map holds values by key, like a `Map` in TypeScript, except that it never changes. |
| [Ranges](/docs/ranges.md) | A range is a span of values between a start and an end, such as a booking's hours or a band of cake sizes. |
| [Numbers](/docs/numbers.md) | Numbers have two namespaces: `integer` operations take values built on `Int`, and `decimal` operations take values built on `Decimal`. |
| [Money operations](/docs/money-operations.md) | The `money` operations make, take apart, add up, share out and convert amounts of `Money`. |
| [Text](/docs/text.md) | The `text` operations count, search, cut, pad and change the case of text, and turn other values into text and back. |
| [Bytes](/docs/bytes.md) | A `Bytes` value is a whole: the `bytes` operations make a new one, `encoding` writes it as text and reads it back, and `hash` digests it. |
| [Encodings](/docs/encodings.md) | The `encoding` operations turn bytes into text and back: Base64 and Base64url for bytes sent as text, hexadecimal for digests, UTF-8 for text as bytes, and percent-encoding for a part of a link. |
| [Hashing and cryptography](/docs/hashing-and-cryptography.md) | The `hash` and `crypto` operations hash values, encrypt and decrypt them, hash and check passwords, sign and check messages, and check tokens and one-time codes. |
| [Signed tokens](/docs/signed-tokens.md) | `crypto.verify_jwt` checks a JSON Web Token (JWT) that another service signed, such as the token a partner's sign-in service gives a person. |
| [Randomness](/docs/randomness.md) | `random` gives your app random tokens, codes, whole numbers, shuffles and samples. |
| [Data formats: JSON, CSV, TSV and JSON Lines](/docs/data-formats-json-csv-tsv-and-json-lines.md) | Four namespaces turn data in a format into your app's types and back, each in one shape. |
| [json](/docs/json.md) | `json` reads and writes JSON. |
| [Logic and bits](/docs/logic-and-bits.md) | `and`, `or` and `not` are the logical operators (Expressions and operators). |

[What is built](/docs/standard-library-built.md) says which of this works today.

## Details

The exact rules, for when you hit an edge case.

| Page | What it covers |
|---|---|
| [SQL forms](/docs/sql-forms.md) | A SQL form is a PostgreSQL 16 expression that gives exactly the result the runtime gives, for every argument. |
| [Coming from TypeScript](/docs/coming-from-typescript.md) | If you know TypeScript, a few of the standard library's choices will differ from what you expect. |