Standard Library Overview

Find a standard function for the task you want to finish, from converting text to reading a file. The compiler checks names, members, and argument types before execution.

Install Topaz through First Program to run the examples.

Choose a capability

Task	Start here	Result to handle
Print text, parse a number, or inspect Unicode	Core Library	A value or `Option`
Transform arrays, find a key, or remove duplicates	Collection Operations	A collection, `bool`, or `Option`
Assemble bytes, calculate a checksum, or compress data	Core Library	Bytes, a number, or `Result`
Read or write a whole file	Files & Resources	`Result` from `FS`
Keep a file open for several operations	Files & Resources	`Result` from `open`, then cleanup with `using` or `defer`
Understand numeric output, collection order, or an execution error	Runtime Behavior	A value or an error that stops execution

An everyday recipe

Save this as overview.tpz.

TOPAZ

let parsed: Option<int> = toInt("42")
let values: Array<int> = Array.of(1, 2, 3)
let doubled = map(values, value => value * 2)

print("{parsed}:{doubled}")

Run topaz run overview.tpz in the folder containing that file.

Output

Some(42):[2, 4, 6]

toInt("42") returns Some(42). Changing the input to "x" gives None. Both are Option values, so the caller can handle a failed conversion. map doubles each array element and keeps the order.

Use Result when an operation returns an error reason, such as a failed file read. A runtime error, or fault, stops execution. Invalid names and argument types are checking errors. See Null, Option, Result & Faults for handling these cases.

Find names and imports

Functions such as print and toInt are available without an import. So are the Option constructors Some and None, and the Result constructors Ok and Err.

A namespace groups related functions under one name. For example, Math.sqrt calls sqrt in Math. These built-in namespaces are available without imports.

Task	Namespace
Store ordered elements	`Array`
Find values by key	`Map`
Keep unique elements	`Set`
Read or write data formats	`JSON`, `CSV`, `TOML`, `URL`
Store or assemble bytes	`Bytes`, `ByteBuffer`
Encode or compress data	`Encoding`, `Codec`
Calculate hashes or checksums	`Hash`
Match text patterns	`Regex`
Calculate with numbers	`Math`, `BigInt`, `Decimal`
Work with calendar dates	`Date`
Access files or construct paths	`FS`, `Path`
Parse command-line arguments	`Cli`
Check assertions in the test profile	`Test`

Package code can also import the toolchain's std.* modules, including helpers for generators and parsers. An imported module with the same name hides the built-in namespace in that file. The self compiler and Rust reference compiler apply the same name lookup rules.

Exact boundaries

A profile specifies which operations a program may use. File and other host operations also need support from the environment running Topaz. Importing a module does not grant filesystem, network, process, environment, clock, or database permissions.

String positions count Unicode scalar values. A scalar is one Unicode code point outside the surrogate range. Byte APIs state when they count bytes.
Collections keep their specified iteration and snapshot order.
Parsing and decoding return the declared Option or Result.
Invalid arithmetic and invalid direct array access can stop execution with a fault.
Test.*, the free assert function, and std.test require the test profile.
Unknown names, modules, and members are rejected during checking. Check the spelling and the API for that type.

Continue by task

Core Library for numbers, text, and bytes.
Collection Operations for lookup and mutation.
Files & Resources for reading, writing, and closing files.
Runtime Behavior for output and execution errors.