Topazdocs
Standard Library & Runtime

Standard Library Overview

Choose the standard-library capability that fits an everyday task and its failure model.

Start with the task, not the API inventory. The standard library gives ordinary programs a small checked surface for values, collections, files, and host boundaries. Unknown names and members fail while checking instead of falling through to a host-language method.

Choose a capability

What you need to doStart hereFailure shape
Print text, convert a value, inspect Unicode, or transform valuesCore LibraryA value, Option, or the helper's declared Result
Store ordered items, look up a key, or keep unique valuesCollection OperationsUsually a value, bool, or Option
Read or write one whole fileFS.readText, FS.writeText, FS.readBytes, or FS.writeBytesResult
Hold a file open across several operationsopen with using or deferResult, followed by lexical cleanup
Understand printing, numbers, order, or a runtime stopRuntime BehaviorA documented value or a loud fault

Choose Array for ordered items, Map for key-to-value lookup, and Set for unique values.

Use Option when absence is an ordinary answer, such as a missing map key. Use Result when external input or a host effect can fail with a useful reason. A fault means the running program violated a contract, while an invalid call or type is rejected statically.

An everyday recipe

This program parses text and transforms an array. toInt uses Option because text may contain no integer; map returns a new array in input order.

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}")
Output
Some(42):[2, 4, 6]

Some(42) keeps the successful parse explicit. If the text were not an integer, the first part would be None; the library would not invent 0 or throw a catchable exception.

How the surface is organized

Prelude functions and constructors such as print, toInt, Some, None, Ok, Err, map, filter, and reduce need no import. Built-in namespaces cover focused families such as Math, Bytes, Hash, FS, and Path. Package code may also use the fixed std.* modules documented by the current toolchain. These are checked exports, not dynamic host namespaces.

The wider surface includes encodings, hashes, paths, command-line parsing, regular expressions, CSV, TOML, JSON, URLs, dates, large integers, decimals, generators, parsers, and bounded host capabilities. Open the focused page for the exact signature and target boundary instead of assuming that a similarly named host API exists.

Common correction: importing a standard module does not grant filesystem, network, clock, environment, process, or database authority. Host effects work only in a profile and environment that provide that capability.

Exact boundaries

  • String positions use Unicode scalars unless an API explicitly says bytes.
  • Collection iteration and snapshots preserve their documented order.
  • Parsing and decoding preserve their declared Option or Result failure.
  • Invalid arithmetic and contract violations remain loud.
  • Test.*, free assert, and std.test are test-profile only.
  • Unknown direct names, virtual modules, and members are static diagnostics.

Continue by task