Home / Docs

Standard library

Release v0.4.0
Una v0.4.0 serves the stable editions 0.1, 0.2 and the preview editions 0.3, 0.4, 0.5. An item of a preview edition is marked with it, and may change before that edition is declared stable (Editions).

Status: Normative, v0.1, with the additions of later editions marked by edition. The standard library is part of the Trusted zone. Everything not listed here does not exist in v0.1. This chapter covers the prelude, std.host and std.testing; the other standard modules are specified with their constructs: std.time and std.drive in spec/26 §2 (edition 0.4), std.limit in spec/27 §10 (edition 0.4), and std.collections in spec/28 §2 (edition 0.5, a preview).

1. Prelude

The prelude is imported into every module.

Types: Int, Nat, Bool, Text, Unit, List[T], Option[T] (Some(value), None), Result[T, E] (Ok(value), Err(failure)), Hashed.

Functions. All are pure and cannot fail. Contracts shown are part of their signatures and are used as hypotheses by callers.

Signature Contract
abs(x: Int) -> Int ensures result >= 0 and (result == x or result == -x)
min(a: Int, b: Int) -> Int ensures result <= a and result <= b and (result == a or result == b)
max(a: Int, b: Int) -> Int ensures result >= a and result >= b and (result == a or result == b)
is_digits(t: Text) -> Bool none (use inside opaque predicates)
starts_with(t: Text, prefix: Text) -> Bool none
trim(t: Text) -> Text ensures result.len <= t.len
to_int(t: Text) -> Option[Int] none
is_empty[T](xs: List[T]) -> Bool ensures result == (xs.len == 0)
first[T](xs: List[T]) -> Option[T] ensures (result is None) == (xs.len == 0)
at[T](xs: List[T], index: Int) -> Option[T] ensures (result is None) == (index < 0 or index >= xs.len)
append[T](xs: List[T], item: T) -> List[T] ensures result.len == xs.len + 1
contains[T](xs: List[T], item: T) -> Bool none
map[T, U](xs: List[T], each: fn(T) -> U) -> List[U] ensures result.len == xs.len
filter[T](xs: List[T], keep: fn(T) -> Bool) -> List[T] ensures result.len <= xs.len
first_where[T](xs: List[T], keep: fn(T) -> Bool) -> Option[T] none
fold[T, U](xs: List[T], initial: U, step: fn(U, T) -> U) -> U none
sum(xs: List[Int]) -> Int none
is_some[T](o: Option[T]) -> Bool ensures result == (o is Some)
or_else[T](o: Option[T], default: T) -> T none
is_ok[T, E](r: Result[T, E]) -> Bool ensures result == (r is Ok)

Higher-order prelude functions accept only pure, non-failing lambdas in v0.1 (effect polymorphism is deferred).

(v0.2, ADR 0062.) In edition 0.2, map, filter, fold and first_where declare uses of and fails of their function parameter (each, keep, step), so they take effectful and failing functions.

(v0.2, ADR 0066.) In edition 0.2, min, max, contains and sum are generic over constrained types, and the prelude gains sort (spec/20 §6). abs stays Int-only.

(v0.2, ADR 0069.) In edition 0.2, the prelude gains empty_map() and the kind Entry[K, V]; the operations of a map are built-in methods of the receiver (spec/21 §2).

(v0.2, ADR 0070.) In edition 0.2, the prelude gains the text functions of spec/22 §2 and the kind ParseError (spec/22 §4).

(v0.2, ADR 0073.) In edition 0.2, the prelude gains the kinds Json, JsonNumber and JsonError, the predicate is_json_number, and the functions parse_json, to_json and quote_json (spec/23).

(v0.2, ADR 0056.) The prelude gains set[T](edit xs: List[T], index: Int, item: T) -> Unit, with requires 0 <= index and index < xs.len and ensures xs.len == old(xs).len (spec/17 §8).

(v0.2, ADR 0057.) The conversions, wrapping, saturating and bit operations of fixed-width integers are built-in methods resolved by the receiver, not prelude functions (spec/18 §4, §5). to_int on Text keeps the meaning above.

Result labels (ADR 0038 D3, ADR 0051). The parameters of these functions that are not functions accept arguments of any label, and their results carry those labels as follows (spec/07 §7 rule 8):

The native implementations declare these labels explicitly.

Text works on Unicode scalar values: .len counts them; is_digits holds when every character is an ASCII digit, so it holds of the empty text; trim removes Unicode whitespace at both ends; to_int reads an optional - followed by ASCII digits; starts_with compares scalar values; contains and == are structural; Text orders by scalar values (ADR 0032).

What the functions compute (#692). Beyond their contracts, the prelude's functions compute the following, in the interpreter and in the native backend alike (spec/16 §5). Positions in a list count from 0.

The prelude's types mean:

2. Built-in operations

.len on Text and List, arithmetic, comparisons, equality and text interpolation are built in (spec/09 §2). Hashed supports only == and !=; it cannot be interpolated or converted to Text (U2001).

3. Host capabilities (part of the prelude)

The host capabilities are declared in the module std.host and are in scope in every module through the prelude (spec/10 §11 rule 8). A module MAY also import them, with their failure kinds, from std.host (spec/10 §11 rule 10).

Capability Operation Fails Accepts Notes
Console print(line: Text) -> Unit public Writes the line and a newline to stdout
Clock now() -> Int public Milliseconds since the Unix epoch
Env get(name: Text) -> Option[internal Text] public Reads a process environment variable
Files read(path: Text) -> internal Text FileError public Path relative to the grant prefix
Files write(path: Text, content: Text) -> Unit FileError internal Path relative to the grant prefix
Keys hmac(key_name: Text, data: Text) -> internal Hashed KeyError public for key_name, any label for data HMAC-SHA-256 with a named key; the result carries the label of data
una
kind FileError = NotFound | Denied | Io
kind KeyError = | UnknownKey

(v0.2, ADR 0074.) In edition 0.2, std.host also declares the capability Http and the kinds Header, Response and HttpError (spec/24).

(v0.4, ADR 0123.) In edition 0.4, std.host also declares the capability HttpServer, the kinds Method, Param, Request, Exchange, Status, Reply and ServeError, and the opaque type ReplyRight (spec/31 §1). Unlike the other host capabilities, the prelude does not put these names in scope: a module imports them from std.host, and an import of one is never redundant (spec/10 §11 rule 10).

4. std.testing

Usable only in test code (ADR 0028, ADR 0043):

  1. A function of std.testing is called only in example lines and in the operation bodies of handlers that are installed only by given lines of examples (tests, written test in edition 0.3, spec/08 §2, ADR 0105; the messages name them by the edition's word). A call outside a handler operation body or an example is U3015.
  2. A handler whose operation bodies use std.testing and that is installed by a with binding is U3015 at the with binding, with the use of std.testing as a related span.
  3. A function of std.testing used as a value, not called, is U3015 everywhere, in handler bodies and examples included.
Signature Purpose
fake_hash(seed: Int) -> internal Hashed Deterministic Hashed value for tests; equal seeds give equal values
elapse(d: Int of Millisecond) -> Unit, requires d >= 0 (Edition 0.4, ADR 0116 rule 19.) Moves the test's virtual clock forward by d at once, without waiting (spec/26 §8)
test_request(method: Method, target: Text, body: Text) -> Request, fails TestRequestError (Edition 0.4, ADR 0123 rule 21.) The request the host would read for method, target and body, with the header host: test; Refused where the host would answer 400 (spec/31 §8)
test_exchange(request: Request) -> Exchange (Edition 0.4, ADR 0123 rule 21.) An exchange of request with a fresh reply right (spec/31 §8)

(Edition 0.4, ADR 0123 rule 21.) std.testing also declares pub kind TestRequestError = | Refused.